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This publication contains detailed information necessary to design and 
prepare application programs to execute under either of two IBM program 
products: CICS/DOS/VS (5746-XX3) and CICS/OS/VS (5740-XX1). It is 
intended for use mainly by application programmers, but will be useful 
also for system programmers and system analysts. 

This publication consists of eight parts, the first seven comprising 
one or more chapters and the eighth containing appendixes. Each of the 
first seven parts (except Part 1) contains information on a particular 
topic, both procedural and reference. In general, each chapter consists 
of the following: 

• A brief introduction to the facilities available by specifying the 
macro instructions that are described in detail in the remainder of 
the chapter. 

• The syntax of each macro instruction in the standard form 

(described in Chapter 1.2). 

• The operands, in alphabetical order, that can be specified with the 
macro instructions. 

Where appropriate, examples in the three programming languages 
(Assembler, COBOL, and PL/I) that can be used with CICS/VS have been 
included. 

Part 1 is an introduction to macro—level application programming. It 
compares the CICS/VS DB/DC system with the conventional batch system of 
data processing. It also describes the general format of a CICS/VS 
macro instruction and explains the syntax notation used throughout the 
publication. 

Part 2 describes symbolic storage definition. This, together with 
addressability, must be specified in the application program to enable 
the application program to be executed under CICS/VS. The preparation 
of an application program for execution is described in the CICS/VS 
S ystem Programmer's Guides . 

Part 3 describes data base operations: file control (including 
browsing) and DL/I services* 

Part 4 describes data communication operations: terminal control, 
basic mapping support, and batch data interchange. 

Part 5 describes control operations: interval control, task control, 
program control, storage control, transient data control, and temporary 
storage control. 

Part 6 describes built— in functions: table search, phonetic 
conversion, data field verification, data field edit, bit manipulation, 
input formatting, and weighted retrieval. 

Part 7 describes error handling, debugging, and recovery/restart 
services: trace services, dump services, journal services, and 
recovery/restart services* 

Part 8 consists of appendixes. These include sample programs, BMS 
examples, fields that make up the application programming interface 
(API) , and translate tables. 
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In this publication, the term VTAM refers to ACF/VTAM, to ACF/VTAME 
(CICS/DOS/VS only), and to the Record Interface of ACF/TCAM (CICS/OS/VS 
only) . The term TCAM refers both to TCAM and to the DCB Interface of 
ACF/TCAM. The term BTAM refers to BTAM (CICS/OS/VS only) and to BTAM-ES 
(CICS/DOS/VS only) . For further details of system requirements, refer 
to the publication CICS/VS General Information * 

For more information about CICS/VS and related subjects discussed in 
this manual, the reader is referred to the publications listed in the 
Bibliography at the end of this manual. A glossary of terms applicable 
to CICS/VS is provided in the publication CICS/VS Gen e ral In formation. 
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Summary of Amendments for Version 1 Release 5 



This edition (SC33— 0079— 2 ) provides information about the new or 
enhanced features introduced by CICS/VS Version 1 Release 5, as follows: 

• Extensions to the intercommunication facilities, offering: 

— Multiregion operation (MRO) — a new mechanism that allows 
communication between multiple connected CICS/VS regions within 
the same processing system without the use of SNA networking 
facilities. 

— Distributed transaction processing (DTP) — — direct transation— 
to— transaction communication across systems. (This facility is 
not available on MRO.) 

— Intersystem Communication between CICS/VS and IMS/VS. 

— Improved throughput by support of SNA parallel sessions. 

• Enhanced master terminal facilities for interactive control of 
CICS/VS. 

• Command— level interface enhancements: an interactive command 
interpreter, and a new command— level interface with DL/I. 

• Security enhancements, including support for an external security 
manager (for example, the Resource Access Control Facility (RACF) 
program product). 

• Improved monitoring facilities. 

• Further device support, including: 

— additional 3270 support. 

— use of the OS/VS console as a CICS/VS terminal. 

— networking of TWX and WTTY terminals through the Network 
Terminal Option (NTO) program product* 

• Usability and serviceability aids, including a new user exit 
mechanism and facilities in CICS/DOS/VS similar to those provided 
by the FERS service aid. 

Some of the above features are not described in this manual because 
they do not directly affect the macro— level application programmer; for 
information on these, refer to the other CICS/VS manuals listed in the 
bibliography* 
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Summary of Amendments for Version 1 Release 4.1. 

This technical newsletter (SN33— 6243) provides information about the new 
features introduced by CICS/VS Version 1 Release 4*1, as follows: 

Chapter 3.2: Reference to fixed block architecture (FBA) . 

Chapter 4*2: Information about terminal control support for LUTYPE4 
terminals. 

Chapter 4.3: Information about basic mapping support (BMS) for LUTYPE4 
terminals. 

Chapter 4.4: Information about batch data interchange support for 
LUTYPE4 terminals. Information about DFHDI TYPE=SEND 
macro instruction for transmitting data to batch data 
interchange terminals. 

Appendix C: Changes to clarify IBM^ commitment about control block 
fields. 

In addition to the changes described above, minor editorial 
improvements and corrections have been made throughout the publication. 



Summary of Amendments for Version 1 Release 4 

This edition (SC33-0079— 1) provides information about the new features 
introduced by CICS/VS Version 1 Release 4, as follows: 

Chapter 4.2, Terminal Control: new syntax displays have been added 
for the IBM 3270 full function logical unit and the IBM 3270 logical 
unit types LUTYPE2, L0TYPE3 and SCSPRT* 

Chapter 4*3, Basic Mapping Support: references have been added to 
various new devices in the IBM 3270 range; there have been some changes 
and additions to operands of the map definition macro instructions 
(DFHMSD, DFHMDI, and DFHMDF) . In addition, a significant amount of 
editorial work has been carried out to improve the usability of the 
chapter. There has been some rearrangement of the information; in 
particular, the descriptions of all operands of DFHBMS macro 
instructions have been grouped together, arranged alphabetically, and 
placed at the end of the chapter. 

Chapter 7*6, Recovery /Re start: additions have been made to reflect 
the new transaction restart facilities offered by CICS/VS. A new macro 
type, DFHSP TYPE=ROLLBACK, is described. 

Appendix B, BMS Map Definition Example: this is an entirely new 
appendix containing examples of BMS map definition macro instructions. 
(The material previously contained in Appendix B, "Trace Tables," has 
been moved into the CICS/VS Problem Determination Guid e *) 

Appendix C, Inter— Release Compatibility: this appendix has been 
updated. It defines any incompatibilities that exist between the 
application programming interface for CICS/VS Version 1*4 and previous 
versions of CICS/VS as well as listing control fields introduced at 
Version 1*4 that are guaranteed to be unchanged for future releases of 
CICS/VS. 

In addition to the changes described above, minor editorial 
improvements and corrections have been made throughout the publication. 
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Part 1. Introduction 



Chapter 1.1. Macro-Level Application Programming 



The IBM Customer Information Control System/Virtual Storage (CICS/VS) is 
a transaction— oriented data base/data communication (DB/DC) system. It 
can be applied to most online IBM System/370 systems, since it offers 
terminal facilities for many applications: message switching, inquiry, 
data collection, order entry, and conversational and batched data entry. 

CICS/VS works with either the Disk Operating System/Virtual Storage 
| Extended (DOS/VSE) or the Operating System/Virtual Storage (0S/VS1 or 
0S/VS2) . It can be thought of as an extension of the operating system 
or as an interface between the operating system and the user's 
application programs. The system is modular: at system generation or 
initialization, an installation can select the components it needs to 
tailor a CICS/VS system for a given application. 

In conventional batch processing (see Figure 1.1—1), similar 
transactions are grouped for processing, and the application programmer 
plans a series of runs to edit input transactions, update data sets, or 
write output reports. Because the programmer concentrates on 
manipulating data for most efficient handling of each transaction type, 
the data in batch processing becomes closely tied to the program logic 
and has little value for other applications. 

A real— time DB/DC system differs from batch processing primarily in 
the number and types of activities taking place in the system at the 
same time* A batch— processing system schedules each application 
independently and provides data base support unique to each application. 
A DB/DC system controls many random nonscheduled transactions for many 
applications and provides one integrated data base supporting all the 
applications on the system (see Figure 1.1—2)* 

The CICS/VS program product (either CICS/OS/VS or CICS/DOS/VS) 
performs many functions essential to success in real— time DB/DC systems. 
Its major functions can be summarized as follows: 

• Provision of rapid response to simultaneously active online 
terminals 

• Control of a telecommunication network of mixed devices 

• Management of a wide mixture of transactions being serviced by a 
variety of application programs at the same time 

• Control of access to a data base 

• Management of system resources, such as main storage, to keep the 
system in continuous operation 

• Assignment of priorities to optimize use of the processor. 

With these functions assumed by CICS/VS, application programmers can 
concentrate on their particular applications. Programming takes less 
time, debugging is easier, and implementation time and costs are reduced 
accordingly* 

A key consideration in selecting a DB/DC system is its adaptability 
to present and future needs* CICS/VS is a family of systems that 
provides a DB/DC interface to IBM System/370 at most levels of the 
product line, offering a clear path for growth or migration of an 
installation . 
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Figure 1.1—2. Transaction Processing of CICS/VS 

Figure 1.1—3 shows how the CICS/VS data base supports the information 
needs of multiple applications , independently and concurrently. 
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Although application programmers need not be concerned with details 
of CICS/VS structure or performance, they should have a general 
understanding of how CICS/VS components interact to perform essential 
processing steps. CICS/VS consists of six major components, explained 
| in greater detail in the publication CICS/VS Diagnostic Reference . They 
are: 

System management 

System services 

System monitoring 

System reliability 

System support 

Application services 

Each of these components is divided into functions which provide 
services to CICS/VS users. The components that most directly affect the 
application programmer are system management, system monitoring, and 
system reliability. To help the application programmer understand some 
of the ways in which CICS/VS assists him, the system management 
functions are summarized below. 

• Terminal management — provides for communication between terminals 
and user— written application programs through the terminal control 
program. This function supports automatic task initiation to 
process new transactions. The testing of application programs is 
accommodated by the simulation of terminals by sequential devices 
such as card readers, line printers, tape units, or disk storage 
units. 

• File management — provides for the addition, update, direct 
retrieval, and selective retrieval (browsing) of data on BDAM, 
ISAM, and VSAM data base data sets. Additional capabilities 
provided only for VSAM data sets include record deletion, skip- 
sequential processing, key— ordered mass insertion, relative byte 
addressing, search key high/equal, generic key, and locate mode 
processing for read-only requests. Optional access to the DL/I 
facility of the IBM Information Management System/Virtual Storage 

(IMS/VS) is provided under CICS/OS/VS. Such use of DL/I requires 
installation of the IBM program product IMS/VS Data Base System. 

Note : Users of CICS/DOS/VS can interface with the IBM program 
product DOS/VS DL/I through DOS/VS DL/I CALLs, but CICS/VS file 
control macro instructions cannot be used. 

• Transient data management — provides for optional queuing of data 
in transit between user— defined destinations. This function 
facilitates message switching and data collection. 

• Temporary storage management — provides an optional general— purpose 
"scratch pad" function intended for video display paging, 
broadcasting, data collection suspension, conservation of main 
storage, retention of control information, and similar. Where 
multiple records are used and random access to those records is 
required, this function also provides a queuing facility. 

• Storage management — provides control of main storage allocated to 
CICS/VS. Storage acquisition, disposition, initialization, and 
request queuing are among the services performed by this function. 
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• Program management — provides a multiprogramming capability through 
dynamic program management while offering a real— time program fetch 
capability. 

• Time management — provides control of various task functions (for 
example, runaway task control, task synchronization, and system 
stall detection) based on specified intervals of time or the time 
of day* 

• Task management — provides dynamic multitasking necessary for 
effective, concurrent transaction processing, such as priority 
scheduling, transaction synchronization, and control of serially 
reusable resources. This function controls activities within the 
CICS/VS partition or region and is in addition to the multitasking 
or multiprocessing capabilities of the host operating system. 

• Journal management — provides for the creation and management of 
special-purpose seguential data sets, called journals, during real- 
time execution of CICS/VS. Journals are intended for recording (in 
chronological order) data that the user may need in subsequent 
reconstruction of data or events* Examples of such data sets are 
an audit trail, a change— file of data base updates and additions, 
and a record of system transaction activity (often called a log) . 

• Sync point management — works in conjunction with other CICS/VS 
functions such as transient data management and file management, to 
provide for an emergency restart of CICS/VS after abnormal 
termination. The CICS/VS transaction backout program (DFHTBP) or a 
user— written application program can make changes to data base data 
sets or transient data intrapartition queues for tasks "in— flight" 
at time of failure based on information recorded on a system log 
during online execution of CICS/VS* 

CICS/VS also provides dump management and trace management, which are 
used in program debugging. CICS/VS basic mapping support (BMS) 
facilitates information display on a wide variety of terminals and 
provides device independence, terminal paging, and message routing. A 
number of built— in functions are available for use by application 
programs. CICS/VS also provides system service programming to identify 
terminal operators, to give control of the entire system to a master 
terminal, to display real— time system statistics, to intercept abnormal 
conditions not handled directly by the operating system, and to end 
operation by collecting statistics, closing data sets, and returning 
control to the operating system. 

To provide rapid response to terminal users, CICS/VS executes in a 
multitasking mode of operation within its own partition or region. Such 
multitasking within a partition or region is analogous to 
multiprogramming within the total operating— system environment. 
Generally, tasks are initiated as a result of transactions entered at 
terminals. Whenever a task is forced to wait for completion of an I/O 
operation; availability of a resource, or some other cause, processing 
of another task within the system is initiated or continued. 

The processing of a typical transaction is shown in Figure 1.1—4. 
Some general characteristics of application programs to be run under 
CICS/VS and the use of other functions that it provides are explained in 
subsequent parts of this manual* 
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Chapter 1.2. Macro Format and Syntax Notation 



| Application programs to be executed under CICS/VS can be written at the 
| macro level in assembler language, COBOL, or PL/I. Regardless of the 
language used, it is strongly recommended that CICS/VS is allowed to 
perform all supervisory and data management services for applications. 
Such services can be invoked by using CICS/VS macro instructions. 
CICS/VS macro instructions can also be used to reguest dump and trace 
facilities when testing or debugging an application program. Although 
an application program is not precluded from direct communication with 
the operating system, the results of such action are unpredictable and 
performance may be affected. Such action also has a limiting effect on 
migration from CICS/DOS/VS to CICS/OS/VS, a growth path that may become 
highly advisable for the CICS/DOS/VS user. 

CICS/VS macro instructions are written in a format similar to 
assembler—language macro instructions: 



i — : -~ 

I Name | Operation | Operands | Comments 



I ■ ~ 

| blank | DFHxxxxx | One or more operands | Comments for 

I or | | separated by commas | program documentation 

| symbol) | | 

» _ _____ 

The name field must not contain a label if the macro instruction is 
used in a COBOL or PL/I program; however, if a label is desired for the 
macro instruction, it may be placed on the line preceding the macro 
instruction. For COBOL programs, the first six positions may contain a 
sequence number. 

The operation field must begin before column 16 and must contain the 
three— character combination "DFH" in the first three positions of the 
operation field. Up to five additional characters can be appended to 
DFH to complete this symbolic name for the appropriate program or table, 
Since DFH is reserved for CICS/VS macro instructions, no other line may 
begin with this three— character combination. 

The operands field is used to specify the services and options to be 
performed . 

The following general rules apply to the macros described in this 
manual: 

1. Operands that are written in uppercase letters (for example, 
TYPE=INITI&L) are to be coded exactly as shown. 

2. Operands that are written as a combination of uppercase and 
lowercase letters separated by an equal sign are to be coded with 
the keyword on the left as it appears and an appropriate 
substitution for the general class of elements on the right. For 
example, if the format description contains NORESP=symbolic 
address, the user may code NORESP=NORMROUT. 
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3i Commas and parentheses are coded as shown. However, the 

parentheses are required only when more than one operand is 
specified. For example, the following coding is correct: 

TYPE=READ 
TYPE=(READ,WAIT) 

The commas are used as separators, but no comma should precede the 
first operand entry or follow the last one inside parentheses. 
Similarly, no comma should follow the last operand coded for a 
particular macro instruction. 

4. Since a blank character indicates the end of the operand field, the 
operand field must not contain blanks except after a comma on a 
line to be continued or after the last operand of the macro 
instruction. The first operand on a continuation line must begin 
in column 16. 

5. When a CICS/VS macro instruction is coded on more than one line, 
each line containing part of the macro instruction (except the last 
one) must contain a nonblank character (for example, an asterisk) 
in column 72 indicating that the macro instruction has been 
continued on the next line. 

6. If a macro that has positional operands is coded with an invalid 
operand, the operand will be ignored. An error message will not be 
issued. 

7. If a keyword is spelt incorrectly, the operand ma y be treated as an 
invalid positional operand as in point 6. 

| 8. The rules for writing CICS/VS macro instruction operands are the 
j same as those for assembler— language macros. 



SYNTAX NOTATION 

Throughout this manual, wherever a CICS/VS macro instruction is 
presented, the symbols { }, |, [ ], and .** are used in defining the 
instruction format. These symbols are not part of the macro instruction 
and are not coded by the programmer* Their purpose is to indicate how 
the macro instruction may be written, and they should be interpreted as 
follows : 

1. Braces { } are used to delimit parameters from which choices are 
made. For example, 

SEGSET= {symbolic address | YES| ALL} 

which indicates that the coding SEGSET= must be followed by a 
programmer— selected symbolic address, the keyword YES, or the 
keyword ALL. 

2. The vertical stroke | indicates that a choice is to be made. It is 
the same as the use of the word "or." For example, 

[ ,INTRVAL= {numeric value | YES}] 

means that either "numeric value" or "YES", but not both, can be 
specified in the macro instruction. 
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3, Square brackets [ ] denote options. Anything enclosed in sguare 
brackets may or may not be coded, depending on whether or not the 
associated option is desired. For example, 

MODE=[ (MOVE I LOCATE) ] 

If a default value is assumed by CICS/VS in the case of an omitted 
operand, that default value is indicated by underscoring. 

4. An ellipsis ...(three dots) denotes that the immediately preceding 
unit may appear one or more times in succession in the macro 
instruction* 
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Chapter 1.3. Programming Techniques and Restrictions 



Application programs to be run under CICS/VS may be coded at the macro 
level in assembler language, COBOL, or PL/I . Writing a program to be 
run under CICS/VS is not significantly different from writing a program 
to be run on any of numerous computing systems. However, the CICS/VS 
user should be aware that CICS/VS is an online system and that programs 
running under CICS/VS operate in an online environment. Some of the 
basic differences between online systems and the traditional batch- 
processing environment are summarized in Figure 1.3—1. 

Single threading is the execution of a program to process inputs to 
completion, sequentially. Processing of one input is completed before 
another input is acted upon. 

In contrast, multithreading is the capability of using various 
sections of a single program concurrently* Under CICS/VS, for example, 
the first section of an application program may be executing to process 
one transaction- When that section is completed (in general, signaled 
by the execution of a CICS/VS macro instruction that causes a wait) , 
processing of another transaction using a different section of code in 
the same program may ensue. 

Just as there is not usually one clearly superior, correct way to 
solve a problem, so there is not usually one correct way to write a 
program to implement that solution. Nevertheless, there are good and 
bad technigues of programming under CICS/VS. How much time and thought 
should be given to programming style when writing a program? The answer 
depends largely on the expected usage of the program. Will it be used 
once a day or once a year? When used, will it run for two minutes or 
five hours? The frequency and length of use are important factors to 
consider when deciding how much time to spend on programming techniques 
(that is, to devising the optimum solution to a problem) * 

Some of the basic characteristics of application programs to be run 
under CICS/VS are summarized below. These characteristics should be 
viewed as essential to successful operation under CICS/VS (although some 
are not mandatory, they are highly advisable) . 

1. Programs must be quasi-reenterable (see "Quasi— Reenterability", 
later in this chapter) . 

2. CICS/VS macro instructions (rather than programming— language 
statements such as READ, GET, PUT, or WRITE) are included to 
control the functions required in application programs. (See 
Chapter 1.2. "Macro Format and Syntax Notation".) 

3. Input/output areas, temporary storage areas, and work areas are not 
included in an application program. All or portions of these areas 
are defined outside of application programs* The application 
programmer must work with CICS/VS system programmers in defining 
these areas by means of tables within CICS/VS. (See "Storage 
Definition", later in this chapter and Part 2.) 

4. Files are not defined within application programs* As in item 3, 
the application programmer works with CICS/VS system programmers in 
establishing these definitions * (See the CICS/VS System 
Programmer's Reference Manual and applicable operating— system 
publications. ) 
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5. The application programmer must establish addressability in his 
program to CICS/VS storage areas accessed by his program* 

6* Working storage should not be tied up, for example, awaiting a 
reply from a terminal user. 

7. Programs should be as efficient as possible, to work with CICS/VS 
in providing rapid response to terminals. 

| 8. Any feature, option, or statement that will transfer control to 
| the operating system should not be used in a CICS/VS program. 
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Figure 1.3—1. A Comparison of Batch and Online Environments 

The general structure of a CICS/VS application program can be 
summarized as follows: 

• Storage definition statements 

• Program initialization statements 

• Processing statements 
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• Termination statements 

No attempt is made in this text to teach the use of typical 
programming— language statements or general programming technigues within 
assembler language, COBOL, or PL/I. Documentation for these languages 
should be consulted for such information (see the Bibliography at the 
end of this manual) . 

CICS/VS operates in a virtual storage environment. The key objective 
of programming in this type of environment is the reduction of page 
faults — those cases in which a program refers to an instruction or data 
that does not reside in real storage. When this occurs, the page in 
virtual storage that contains the referenced instruction or data must be 
transferred (paged) into real storage. The more paging reguired, the 
lower the overall system performance. 

The application programmer who writes programs to be run in a virtual 
storage environment should understand the following concepts: 

• locality of reference — the consistent reference, during the 
execution of the application program, to instructions and data 
within a relatively small number of pages (compared to the total 
number of pages in a program) for relatively long periods 

• validity of referenc e — the consistent reference to valid data. 
This ensures that few storage references retrieve useless data 

• working set — the number and combination of pages of a program 
needed for satisfactory performance (low paging rate) during a 
given period 

In general, the application program should use technigues to improve 
the locality and validity of reference and to minimize the size of the 
working set at any time during execution of the program, as follows: 

1. To achieve locality of reference, processing should be seguential 
for both code and data, as far as possible. 

a* Initialize data as close as possible to its first use* 

b* Define new data items as close as possible to the items that 
use them. 

c. Define arrays or other data structures in the order in which 
they will be referred to; refer to elements within structures 
in the order in which they are stored, for example, rowwise 
rather than columnwise when using PL/I. 

d. Separate error— handling or unusual-situation routines from the 
main section of a program; they should be subprograms. 

e* Subprograms that are short and used only once or twice (other 
than those in d above) should be coded inline in the calling 
program. 

2. To achieve validity of reference* 
a* Avoid long searches for data. 

b. Use data structures that can be addressed directly, such as 
arrays, rather than structures that must be searched, such as 
chains. 

c. Avoid indirect addressing and any methods that simulate 
indirect addressing. 
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3. To reduce the size of the working set, the amount of storage that a 
program refers to in a given period should be as low as possible* 

a. Write modular programs and then structure the modules according 
to frequency and anticipated time of reference. 

b* Use separate subprograms whenever the flow of your program 
suggests that execution will not be sequential. 

When all page frames in a real storage environment are filled and 
another page must be loaded into storage, a page replacement operation 
is required. The operating system replaces first those pages that have 
not been referred to for the longest period of time. If a page to be 
replaced has been modified, that page must be paged out onto virtual 
storage before the required page can be read in. The more page— out 
operations required, the lower the overall performance of the system. 

To avoid the necessity for page-out operations, the application 
program should be coded so that page— out operations are not required 
when a page containing a portion of the program must be replaced in real 
storage. The program need only avoid modifying instructions or data 
within itself. A program in which neither instructions nor data are 
modified is said to be reenterable. As noted earlier, programs to be 
run in a CICS/VS environment must be quasi— reenterable. For performance 
reasons, it may be wise to make them truly reenterable programs. 

The application program should not attempt to use overlays, that is, 
to incorporate paging techniques. System paging is automatic and 
generally more efficient. 



Application Program Packaging 

The design of an application program for a virtual environment is 
similar to the design of an application program in a real environment. 
The system should have all modules resident so that code on un- 
referenced pages need not be paged in* If the program is dynamic, the 
entire program must be loaded across adjacent pages before execution 
begins. Dynamic programs can be purged from storage if not in use and 
an unsatisfied storage request exists. Allowing sufficient dynamic area 
to prevent purging is less efficient than making the programs resident 
since a dynamic program will not share unused space on a page with 
another program. 

The reference pattern of the application should touch the fewest 
concurrent pages during its execution* 

1. The main line execution should be as straight a line as possible. 
The ideal program executes sequentially with no branch logic 
referencing beyond a small range of address space. 

2. Literals and subroutines should be coded as close to their use as 
possible. This would include LTORG statements at appropriate 
locations in the program. Place constants that are used only once 
near to the place where they are used. Executed instructions 
should be near the EX instruction. Perform and GO TO routines 
should be placed near the caller. 

3. Avoid use of COBOL EXAMINE or VARIABLE MOVE operations since these 
expand into subroutine executions. 

4. Do not alter anything within the program module. An unchanged 
module is reenterable and is not paged out. 
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5. Use the TWA for changeable data during execution, that is counters, 
switches, parameter passing, basic mapping support output area (use 
BMS SAVE) * 

6* Do few or no user GETMAINS to minimize the task»s reference 
pattern. 

7. Avoid LIHKs since it will cause a GETMAIN for a RSA and will search 
the PPT. 

8. Try to keep the execution path straight line by using XCTL. 

9. If specifying data for a CICS/VS service request by explicitly 
assigning a value to a CICS/VS field (for example, in the task 
control area), assign the value immediately prior to issuing the 
service request, with no other service requests intervening. Also, 
reassign the value immediately before issuing any subsequent 
request that needs it. 



Quasi-reenterability 

Application programs must be coded so that they are "serially reusable" 
between entry and exit points of the program. A serially reusable 
portion of an application program is executed by only one transaction at 
a time, and must initialize and/or restore any instructions or data that 
it alters within itself during execution. (It is recommended, however, 
that all applications be truly reenterable to minimize paging.) Entry 
and exit points coincide with the use of CICS/VS macro instructions, 
since an application program loses control only upon execution of a 
CICS/VS macro instruction. 

This required quality of application programs written to run under 
CICS/VS is called "quasi— reenterability," since the programs need not 
meet System/370 specifications for true reenterability. Quasi- 
reenterability allows a single copy of a user— written application 
program to be used to process several transactions concurrently, thereby 
reducing the number of copies of a program that must be in main storage. 

Intermediate exits may be taken during execution of an application 
program. Such exits constitute a transfer of control from the program. 
All switches, data, and intermediate results needed upon subsequent 
return to the program must be retained in a unique storage area such as 
the transaction work area (TWA) * The application programmer must 
provide that unique intermediate storage area by symbolically defining 
it in his program (as described in Part 2). 

A serially reusable application program that has no intermediate 
exits also has the quality of quasi— reenterability. 



Storage Definition 

The macro library supplied with CICS/VS contains symbolic storage 
definitions of CICS/VS control areas, work areas, and I/O areas. It is 
strongly recommended that the application programmer use these 
definitions rather than develop actual or direct displacements in his 
program. This protects the application program in the event of any 
relocation of CICS/VS* 
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The assembler— language programmer includes symbolic storage 
definitions in his program by means of assembler— language COPY 
statements. For the PL/I programmer, the macro library contains 
numerous BASED structures, in the form of dummy control sections 
(DSECTS), that describe CICS/VS control areas. These DSECTs are 
available to the user through the use of ^INCLUDE statements. The COBOL 
programmer uses similar definitions through COPY statements in the 
Linkage Section of the Data Division of his application program. These 
definitions are discussed in Part 2. 



Program Initialization 

In the initialization section of the application program, the assembler- 
language programmer must establish a symbolic base address for his 
program, because this is not done by CICS/VS prior to entry. In doing 
so, he identifies a base register. Register 12 is reserved by CICS/VS 
for the address of the task control area (TCA) for this task. Register 
13 is reserved for the address of the common system area (CSA) . Both 
these registers are initialized by CICS/VS prior to entry and their 
contents must be preserved throughout execution of the program. For 
COBOL and PL/I, this preservation of registers is done automatically by 
CICS/VS. 

Registers 15 through 11 are available to the user and their contents 
are preserved when a CICS/VS macro instruction is executed; the contents 
of register 14 are destroyed whenever a CICS/VS macro instruction is 

| executed. The contents of register 1 are destroyed if parameters are 

| specified on a DL/I call. 

The different types of the DFHPC macro instruction that can be issued 
to transfer control from or to an application program are listed in the 
left— hand column of Figure 1*3—2. The status of all registers upon 
program entry or upon return to a program is as shown in the remaining 
columns. 

Although register 14 contains the program entry address, it is not 
advisable to use register 14 as the base register since it is used by 
CICS/VS to service requests for CICS/VS supervisory and data management 
services. 
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Figure 1.3—2; Register Usage under CICS/VS 



Restrictions 



There are language and other restrictions that the application 
programmer should be aware of when writing programs to be run under 
CICS/VS. 



ASSEMBLER 



If CICS/VS macro instructions are included in an assembler— language 
application program, the assembler instruction COM (define blank common 
control section) must not be used. 



COBOL 



| The use of CICS/VS macro instructions in a COBOL application program 
precludes the use of the following COBOL features: 

1. Environment and Data Division entries normally associated with data 

management services. 

2. File Section of the Data Division. 
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3. Special features: ACCEPT , DISPLAY, EXHIBIT, REPORT WRITER, 
SEGMENTATION, SORT, TRACE, and UNSTRING. 

Any feature that requires an operating system GETMAIN. 

4. DOS compiler options: COUNT, FLOW, STATE, STXIT, or SYMDMP. 

OS compiler options: COUNT, ENDJOB, FLOW, DYNAM, STATE, SYMDMP, SYST, or 
TEST. 

Any option that requires operating system services. 

5. COBOL statements: READ, WRITE, OPEN, CLOSE. 

6. QUOTE option, which signifies that literals are to be delineated by 
quotation marks (for example, "74" ). Because CICS/VS macro 
instructions generate COBOL code using apostrophes to delineate 
literals (for example, •74*), the APOST option must be in effect. 

7. The OPTIMIZE option of DOS Full COBOL Version 3 (5736-CB2.) 

SERVICE RELOAD statements must be coded in programs compiled under 
the following compilers when the OPTIMIZE option is active: 

• OS Full COBOL Version 4 (5734-CB2) 

• OS/VS COBOL Release 1 (5740-CB1) 

• DOS/VS COBOL (5746-CB1) 

If the NOOPTIMIZE option is used, SERVICE RELOAD can, but need not, 
be used* Further details of SERVICE RELOAD appear in "Additional 
Guidelines" in Chapter 2.3. 

CICS/VS macro instructions should not be coded within a COBOL 
statement, since each COBOL statement generated by a CICS/VS macro 
instruction is terminated by a period. 

CICS/VS macro instructions generate COBOL statements which use an 
apostrophe (•) to delineate literals- Code written by the application 
programmer cannot utilize quotes (") to delineate literals. 

Duplicate names may not be used. This requirement is a result of 
preprocessing by the translator before COBOL statements are generated. 

Any COBOL program that is to run under CICS/VS must contain at least 
one CICS/VS macro instruction (for example, DFHPC TYPE=RETURN) for 
proper operation. 

Users of the OS/VS COBOL Release 2 compiler must specify LANGLVL(I), 
and must not use the INSPECT or USE FOR DEBUGGING statements! 

The macro level interface will not support a COBOL program with a TGT 
larger than 4K. If a program generates a TGT greater than 4K the 
command level interface must be used. 
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PL/I 



The following restrictions apply to programs compiled by the PL/I F 
Compiler for CICS/OS/VS* However, if the PL/I Optimizing Compiler is 
used with the PL/I support supplied by CICS/VS, not all the restrictions 
apply* Refer to the PL/I Optimizing compiler Programmer's Guide for 
more information on the applicable restrictions. 

The use of CICS/VS macro instructions in a PL/I application program 
precludes the use of the following PL/I features: 

1. The multitasking built-in functions: COMPLETION, STATUS, PRIORITY. 

2* The multitasking options: PRIORITY, TASK, EVENT. 

3* The PL/I statements: READ, WRITE, GET, PUT, OPEN, CLOSE, DISPLAY, 
DELAY, REWRITE, LOCATE, DELETE, UNLOCK, STOP, HALT, EXIT, and, for 
the PL/I Optimizing Compiler, FETCH and RELEASE. 

4. PL/I Sort/merge. 

5. PL/I error handling. 

| 6. A declaration for a nonstring element variable with the attributes 
| STATIC EXTERNAL but without the INITIAL attribute* (This 
| declaration will generate a common CSECT that cannot be handled by 
| CICS/VS) * 

The use of CICS/VS macro instructions in a PL/I application program 
to be compiled on the PL/I Optimizing Compiler also precludes the use of 
the following compiler options: 

REPORT, FLOW, GONUMBER, GOSTMT. 

An application program written in PL/I must consist of an external 
(MAIN) procedure* Internal procedure CALLs are allowed in a PL/I 
program to be run under CICS/VS, but external CALLs are not. 

Floating— point operations can be used, but CICS/VS does not dump the 
contents of floating— point registers, and programmers should be aware 
that a floating— point interrupt will cause the task to be abnormally 
terminated. 

Any CICS/VS macro instruction operand which defines a name or label 
of a storage area or routine should comply with the Assembler language 
restrictions of eight characters or less. This requirement is a result 
of preprocessing by the Assembler before PL/I statements are generated. 



LINK-EDITING 

Separate COBOL routines cannot be link-edited together. Neither can 
separate PL/I routines* Assembler— language routines may be link— edited, 
but routines invoked by CALL statements must conform to CICS/VS 
application program requirements. Facilities comparable to link— editing 
are provided under CICS/VS through DFHPC TYPE=LINK and DFHPC TYPE=XCTL 
(transfer control) macro instructions, which can be used to set up 
communication between programs. For details of the job control required 
to compile and link— edit application programs refer to the CICS/VS 
S yst em Progra mmer's Guide * 
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OBJECT PROGRAM SIZE 

The object module resulting from any application program must not occupy 
more than 262,136 bytes of storage* 



Assembly-time Service (DFHCOVER Macro) 

In addition to knowing the execution— time considerations discussed in 
this chapter, the application programmer should be aware of an assembly- 
time (or compile— time) service available under CICS/VS: the DFHCOVER 
macro instruction. This macro instruction specifies that the assembler 
or compiler in use print a cover page on two consecutive pages, which 
ensures that the application program listing can be torn off with one of 
the cover pages face up. Useful information (program name, date, time 
of assembly, remarks, and so on) may then be written on the cover page. 

The DFHCOVER macro instruction requires no operands and nothing else 
should appear on the same coding line. 

If the DFHCOVER macro instruction is coded as part of an Assembler- 
language application program, it should be coded as the first 
instruction in the program. If desired, however, this macro instruction 
may be coded after anything that is not vital to the listing (such as 
the TITLE line). 

The first line of a PL/I source program is printed as a header on 
each page of the source listing. This means that when the DFHCOVER 
macro instruction is part of a PL/I application program, the first line 
should be a comment containing information that the application 
programmer wants printed as a header. The second line should contain 
the DFHCOVER macro instruction. The actual PL/I code should begin with 
the third line. 

Since column 1 is used by the DFHCOVER macro for line and page 
spacing under PL/I, column 1 must be defined as reserved for control 
characters and columns 2—72 must be defined as available for data. For 
information concerning PL/I compile— time services, see the DOS PL/I 

Optimizing Compiler Programmer' s Gu ide, the OS P L/I (F) Programmer's 

G uide , and the OS PL/I Optimizing Compiler Programmer's Guide . 

The example in Appendix A shows how the DFHCOVER macro instruction is 
used. 



Testing Responses to Macro Instructions 

As a result of issuing CICS/VS macros, certain error conditions may be 
raised. A programmer can test for these conditions in any of the 
following ways: 

• Code the appropriate operands in the macro being issued. Each 
macro syntax display lists the operands available. 

• Code a DFHXX TYPE=CHECK macro immediately following the particular 
macro by which the service is requested* 

• Code instructions, following the macro by which the service was 
requested, that test the contents of certain CICS/VS control areas. 
The relevant control areas and the meaning of the returning bit 
patterns are discussed in each chapter that describes the services. 
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I If the programmer does not check the response to a request, program 
| flow continues with the next sequential instruction. 
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Part 2. Storage Definition 
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CICS/VS provides symbolic storage definitions in the form of dummy 
sections (DSECTs) that describe the layouts of a number of storage 
areas. These storage definitions are contained in the CICS/VS libraries 
and can be copied into application programs where, in combination with 
user-defined layouts of the user's sections of the storage areas, they 
provide symbolic addressing (addressability) to the storage areas. 



CICS/VS Storage Areas 

The storage areas for which symbolic storage definitions are provided 
consist of control areas, for example the Common System Area (CSA) , work 
areas, for example the File Work Area (FHA) , and input/output areas, for 
example the Terminal Input/Output Area (TIOA) * CICS/VS storage areas 
are summarized in Figures 2.1—1 and 2*1—2. 

Some of these storage areas are acguired by CICS/VS during system 
initialization, others are acguired and released during execution of the 
system. Some areas are acguired by CICS/VS; some by the application 
program; and some by either CICS/VS or the application program. 

All CICS/VS storage areas, with the exception of the journal control 
area (JCA) and VSAM work areas (VSHAs), consist of two sections. The 
first is the system section , used primarily by CICS/VS; the second is 
the user section , defined and used exclusively by the application 
program. This division exists whether the storage areas are acguired 
during system initialization (for example, the common system area) or 
acguired during execution (for example, a terminal input/output area) . 

All CICS/VS pointers (areas containing addresses) are four bytes in 
length . 

A storage accounting field comprising eight bytes preceding and eight 
bytes following each storage area is built by CICS/VS for every storage 
area acguired for the user. If this field is altered or destroyed, 
CICS/VS may be abnormally terminated. 

The common system area (CSA) and the task control area (TCA) must be 
defined in every application program; other areas are defined as needed* 
It is the user's responsibility to define the CSA and TCA as well as 
other storage areas reguired by the application program. 

Identifiers such as CSA and TCA, used in this manual, are also used 
in symbolic names, or labels, within CICS/VS modules and must be used by 
the application programmer to refer to the data that they represent. 
Names of fields within a storage area generally begin with the 
characters of the label for that area. For example, TCA stands for Task 
Control Area, TCAFCAAA is a field in the TCA that points to a Facility 
Control Area, TCASCSA is a field in the TCA that points to a Storage 
Control Storage Area, and so on* 
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The letters A through G in Figure 2.1—1 denote the following: 

A 



B 



Assembler language only. 

Alternatively, the TCAFCAAA may point to the address of a DCT 
entry or to the address of an automatic initiate descriptor 
(AID) . 

C 

COBOL equivalent: 

01 DFHTCTTE COPY DFHTCTTE. 
MOVE TCAFCAAA TO TCTTEAR* 

PL/I equivalent: 

^INCLUDE DFHTCTTE; 

D 

EOB = End of Block* 

E 

TCAFCAA, TCATSDA, and TCATDAA : The same location within the 
TCA is used for these three pointers, only one of which is 
current at any given time* 

F 

TCASCSA may also point to an area to be released by a DFHSC 
TYPE=FREEMAIN macro instruction. 

G 

After a DFHPC TYPE=LOAD macro instruction, TCAPCLA points to 
the beginning address of the loaded program. 

Throughout Figure 2*1—1, the characters 1L)6}f represent a four— byte 
field in which the first two bytes define the length of the area. 
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Figure 2*1-1* Summary of CICS/VS Storage Areas 
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Transient Data Output Area (DFHTDOA) 
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TD.OADBA - TDOA Data Begin Address 

TDOASAL — TDOA Storage Accounting —area Length 
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Figure 2*1—2. CICS/VS System Sections 
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C opying Symbolic Storage Definitions 

Depending on the programming language used, a statement of one of the 
forms shown below is required to copy a symbolic storage definition into 
an application program. 

1. Assembler— language COPY statement of the form: 

COPY name 

2. COBOL COPY statement of the form: 

01 name COPY name, 
specified in the Linkage Section of the Data Division. 

3. PL/I preprocessor statement of the form: 

^INCLUDE library (member) ; 

or 
^INCLUDE member; 

For example, assume that one or more terminal input/output areas 
(TIOAs) are to be acquired during program execution. One of the 
statements below must be included: 

Assembler: COPY DFHTIOA 

COBOL: 01 DFHTIOA COPY DFHTIOA. 

PL/I: ^INCLUDE DFHTIOA; 

This statement copies the storage definition as a description or map 
of the storage area into the application program, but does not aquire 
storage for it* As pointed out above, sometimes CICS/VS acguires the 
area; in other cases, the user acquires it. 



Addressabilit y 

The storage definition that has been copied into the application program 
must be mapped over the storage area acguired. This is done by moving 
the address of the area (stored in a particular location by CICS/VS) 
into a base locator for that area* Addressability through this base 
locator is limited to 409 6 (0 through 4095) bytes* Depending on the 
programming language, a statement of one of the following forms will 
normally be used to establish addressability to the area: 

1* Assembler— language statement of the form: 

L base— locator , lo cat ion-contain in g-ad dress 

2. COBOL statement of the form: 

MOVE location-containing— address TO base— locator* 

3. PL/I based pointer assignment of the form: 

base— locator = location— containing-address; 
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For example, assume that a terminal input/output area (TIOA) has been 
acquired during program execution* TCASCSA is a four— byte field in the 
TCA that contains the address of the storage area that has been 
acquired- TIOABAR is the TIOA base address register* One of the 
statements below must be executed: 



Assembler: L TIOABAR, TCASCSA 
COBOL: MOVE TCASCSA TO TIOABAR* 



PL/I: 



TIOABAR=TCASCSA; 



Figure 2*1—3 contains the names used in copying CICS/VS— provided 
symbolic storage definitions into an application program and the names 
that represent base addresses used in establishing addressability. 
These symbolic names are used in Figures 2.1—1 and 2.1—2, which show how 
the areas are related and give a summary of the contents of each area. 
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Figure 2.1—3* Symbolic Names and Base Addresses of CICS/VS Storage 
Areas 



Chaining of CICS/VS Storage Areas 

Storage acquired by the application program through CICS/VS storage 
management is controlled by chaining together all storage associated 
with a task* This chaining allows CICS/VS to release all storage 
associated with the task, either upon request from the user or when the 
task is terminated, normally or abnormally. 
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The common system area (CSA ) , whose address is provided by CICS/VS, 
points to the task control area (TCA) which in turn points to the other 
storage areas required by the task. The TCA is the head of the chain of 
storage associated with each task, except for TIOAs, which are chained 
from the TCTTE. Figure 2.1-4 illustrates the chaining of CICS/VS 
storage areas and indicates the symbolic base address used to locate 
each storage area. 



Required Storage Areas 

At least two storage area definitions, namely, those for the CSA and the 
TCA, are required in every application program to be run under CICS/VS. 
The following sections describe these areas. Services performed by 
CICS/VS components are mentioned as necessary. Some tables that are 
basic to CICS/VS operation are also mentioned* These tables are 
explained in greater detail in the CICS/VS System Programmer's Reference 
Manual* 



Common System Area (CSA) 

The Common System Area (CSA) contains areas and data required for the 
operation of CICS/VS. It can be extended to include a user— defined 
common work area (CWA) that can be referred to by application programs. 

Data in the CSA that is required for the operation of CICS/VS 
includes: 

CICS/VS save areas 

Addresses of CICS/VS management programs 

Control system and user statistics accumulators 

Addresses of CICS/VS system control tables 

Common system constants 

System control parameters 
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Figure 2*1—4* Chaining of CICS/VS Storage Areas 
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Common Work Area (CWA ) 

The Common Work Area (CWA) is an area within the CSA that can be used by 
application programs for user data that needs to be accessed by any task 
in the system. This area is acquired during system initialization and 
its size is determined by the system programmer at system generation. 
It is initially set to binary zeros. Its contents can be accessed and 
altered by any task during CICS/VS operation. 

Addressability for the CWA is provided when copying the CICS/VS 
storage definition for the CSA. However , addressability is limited to a 
combined total of 4096 (0 through 4095) bytes for the CSA and CWA. 
Addressability for any portion of the CWA extending beyond the 4096— byte 
limit is the responsibility of the user* 

Since the CWA is available to any task while it has control of the 
system, it is not advisable for an application program to use this area 
for retention of data when requesting CICS/VS services; instead, it 
would be better to use the transaction work area (TWA) which has been 
designed to be used by individual tasks for their own purposes. The TWA 
is described later in this chapter. 



Task Control Area (TCA) 

The Task Control Area (TCA) is an area of main storage acquired by 
CICS/VS when a task is initiated by the task control program. Once 
acquired, the TCA exists until the task is terminated. It contains the 
current status of the task, its relative dispatching priority, and 
parameters and information being passed between CICS/VS and the 
application program. During execution of the task, the user can change 
the priority through task management services; further processing of the 
task is scheduled accordingly. 

The TCA provides the following items for its associated task: 

• Register save areas 

• Unique fields (parameter areas) for communicating requests to 
CICS/VS 

• Address of the related Facility Control Area (FCA ) 

• Task storage chain addresses 

The TCA makes no provision for residual data such as statistics. 
However, the TCA can be extended to include a transaction work area 
(TWA) , the size of which is determined by the user to meet the needs of 
the transaction. (See "Transaction Work Area", later in this chapter.) 

The TCA consists of three parts: 

• CICS/VS system section 

• Communication section 

• Optional Transaction Work Area (TWA) 

The CICS/VS system section contains addresses and data needed by 
CICS/VS to control the task. Access to this section is limited to 
CICS/VS management and service programs. 

The communication section is used by CICS/VS and by user— written 
application programs for communication between the application program 
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and CICS/VS management and service programs i CICS/VS functions 
sometimes overwrite some of the fields in the communication section of 
the TCA. The assignment of required fields in the TCA for a particular 
CICS/VS request must therefore be done immediately prior to issuing the 
request, with no other requests intervening. 

The optional transaction work area is reserved for the exclusive use 
of the application program. 

In those cases in which a task is initiated from a terminal (nearly 
always the case) , CICS/VS places into the TCA the address of the 
terminal control table terminal entry (TCTTE) associated with the 
terminal. The TCTTE, in turn, contains the address of the terminal 
input/output area (TIOA) . 



msaction W ork Area (TWA) 

The Transaction Work Area (TWA) is an extension of the TCA and is 
created at the option of the user to provide a work area for a given 
task. The TWA can be used for the accumulation of data and intermediate 
results during the execution of the task* It can also be used when the 
amount of working storage for a task is relatively static, when data 
must be passed between user— written application programs, or when data 
must be accessed by different programs during transaction processing. 
During multiple entries of data for a transaction, the application 
programs might retain the data in the TWA. This approach cannot be used 
for multiple transactions; the TWA is released automatically at task 
termination* 

The size of the TWA for the task must be determined by the 
application designer and must be specified in the program control table 
by the system programmer at system generation. The TWA must be defined 
immediately following the definition of the TCA in the application 
program. The sizes of TWAs within the system vary according to the 
needs of the transaction. The TWA is initially set to binary zeros. 
(For a discussion about establishing the TWA, see the explanation of the 
program control table in the CICS/VS Sys t em Programmer's Reference 
Manual . 

Addressability of the TWA is provided when copying the CICS/VS 
storage definition for the TCA. However, addressability is limited to a 
combined total of 4096 (0 through 4095) bytes for the TCA and TWA. 
Addressability for any portion of the TWA extending beyond the 4095-byte 
limit is the responsibility of the user. 
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The Assembler— language programmer must define storage for the CICS/VS 
control areas and any other storage areas required for the processing of 
the application program. This is done by using the Assembler— language 
COPY statement to (1) copy the appropriate symbolic storage definitions 
into the application program and (2) specify the names of the storage 
areas being defined* All registers are available, except registers 12 , 
13, and 14 (which are used by CICS/VS)* 

All application programs must contain statements to copy the symbolic 
storage definitions for the common system area (CSA) and the task 
control area (TCA) * If a terminal is to be used, the storage definition 
of a TCTTE must be copied also* The expansions of the CICS/VS macro 
instructions used in an application program refer to fields within these 
areas, so their locations must be identified. Whether additional 
definitions must be copied depends on the processing requirements 
(storage areas and macro instructions used) of the application program. 



Storage Defined During Initialization 

During CICS/VS initialization, the CSA is allocated as part of the 
CICS/VS nucleus. For each terminal that is to be used, a terminal 
control table terminal entry (TCTTE) must be included in the terminal 
control table (TCT) . 



COMMON SYSTEM AREA (CSA) 

The statement 

COPY DPHCSADS 

copies the symbolic storage definition for the CSA and assigns register 
13 as its base register* 

If CICS/VS is generated to include a common work area (CWA ) , a 
symbolic definition for that area must be included immediately following 
the COPY DFHCSADS statement. In the following example, a total of 16 
bytes of storage are defined by the three DS statements. It is assumed 
that a CWA of at least 16 bytes has been defined. 

COPY DPHCSADS 

BUCKET1 DS P 

BUCKET 2 DS P 

TEMPNAME DS CL8 
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TERMINAL CONTROL TABLE TERMINAL ENTRY (TCTTE) 

The statement 

COPY DFHTCTTE 

copies the symbolic storage definition for the TCTTE. This definition 
can be used to obtain the address of the current terminal I/O area (the 
current terminal control table terminal entry data address, or TCTTEDA) 
or to request a terminal control service via the DPHTC macro 
instruction. An EQU statement must be included to set up a base 
register for the TCTTE, equating the label TCTTEAR to a general— purpose 
register. Addressability must also be established for the TCTTE by 
loading the address at TCAPCAAA into TCTTEAR. The following is an 
example of the coding reguired: 

TCTTEAR EQU 5 

COPY DFHTCTTE 



TCTTEAR, TCAPCAAA 



Storage Defined During Execution 

During execution of a task, the TCA, TIOA, and other storage areas 
required by the task are allocated by CICS/VS storage management upon 
request from either the application program or CICS/VS* The application 
program must include symbolic storage definitions for these storage 
areas by using COPY statements as described below. 



TASK CONTROL AREA (TCA) 

The statement 

COPY DFHTCADS 

copies the symbolic storage definition for the communication section 
only of the TCA and assigns register 12 as the base register for the 
whole of the TCA. If the application program requires the use of a 
transaction work area (TWA) , DS statements for the TWA must immediately 
follow the COPY statement. The following is an example of the coding 
required to symbolically define storage for both the TCA and TWA. In 
the example, a total of 53 bytes of storage are defined by the four DS 
statements. It is assumed that a TWA of at least 53 bytes has been 
defined in the PCT for the transaction* 

COPY DPHTCADS 
NAME DS CL20 
STREET DS CL20 
CITY DS CL10 
STATE DS CL3 
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TERMINAL INPUT/OUTPUT AREA (TIOA) 



The statement 

COPY DFHTIOA 

copies the symbolic storage definition for the CICS/VS system section of 
the TIOA* This storage definition should precede the user's definition 
of a terminal input or output message* The user must code an EQU 
statement to set up a base register for the TIOA, equating the label 
TIOABAR to a general-purpose register! Any action that requires a TIOA 
can then be specified. For example, a DFHSC TYPE=GETMAIN macro 
instruction requesting CICS/VS storage control to obtain dynamic storage 
for a TIOA for the program can be specified, as follows: 

TIOABAR EQU 9 

COPY DFHTIOA 

NAME DS CL20 

STREET DS CL20 

DS CL5 



DFHSC TYPE=GETMAIN,NUM3YTE=45,CLASS=TERMINAL 
L TIOABAR, TCASCSA 

For additional information about obtaining storage, see "Obtain and 
Initialize Main Storage (TYPE=GETMAIN) " in Chapter 5.5. 



FILE INPUT/OUTPUT AREA (FIOA) 



The statement 

COPY DFHFIOA 

copies the symbolic storage definition for the CICS/VS system section of 
the FIOA. This storage definition should precede the user^s defined 
layout of a file input or output area when reading an unblocked record 
without updating or segmenting, or when reading DAM blocked records 
without deblocking. If desired, the user can identify that the area 
returned in response to a user file request is an FIOA, rather than an 
FWA or VSWA, by testing label FIOAIND for a mixed condition using mask 
FIOAM. 

The user must code an EQU statement to set up a base register for the 
FIOA, equating the label FIOABAR to a general-purpose register* The 
FIOA is automatically acquired by CICS/VS file management whenever a 
request is made by the user to access a data base data set* If data is 
retrieved using the Indexed Sequential Access Method (ISAM) under 
CICS/OS/VS, a 16-byte filler must be defined prior to the user»s data 
definition* The user must establish addressability for an FIOA acquired 
in response to a DFHFC macro instruction before referring to the FIOA. 
The following is an example of the coding required; it includes the 
optional test for FIOA identification. 
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FIOABAR EQU 


7 


COPT 


DFHPIOA 


DS 


16X 


NAME DS 


CL20 



STREET DS 



CL5 



OS/VS ISAM FILLER 



i 
L 

TM 
BM 



FIOABAR,TCAFCAA 

FIOAIND,FIOAM 

GOTFIOA 



WAS FIOA RETURNED? 
YES 



FILE WORK AREA (FWA) 



The statement 

COPY DFHFWADS 

copies the symbolic storage definition for the CICS/VS system section of 
the FWA* This storage definition should precede the user^s defined 
layout of a file record area when reading or updating an existing 
blocked or segmented record, when adding a new record to a file, or when 
retrieving records using the browse feature* If desired, the user can 
identify that the area returned in response to a user file reguest is an 
FWA, rather than an FIOA or VSWR, by testing label FWAIND for a ones 
condition using mask FWAM. 

The user must code an EQU statement to set up a base register for the 
FWA, eguating the label FWACBAR to a general— purpose register. The user 
must also establish addressability for an FWA acquired in response to a 
DFHFC macro instruction prior to any reference to the FWA. The 
following is an example of the coding reguired; it includes the optional 
test for FWA identification: 



FWACBAR 


EQU 


7 






COPY 


DFHFWADS 




NAME 


DS 


CL20 




STREET 


DS 


CL30 




ZIPCODE 


DS 


CL5 






* 
J 
L 


FWACBAR, TCAFCAA 






TM 


FWAIND, FWAM 


WAS FWA RETURNED? 




BO 


GOTFWA 


YES 



VSAM WORK AREA (VSWA) 

The statement 

COPY DFHVSWA 

copies the symbolic storage definition for the CICS/VS system section of 
the VSAM work area (VSWA) and must be present in all programs using 
locate mode I/O* (See "Direct Retrieval (VSAM Locate Mode)" in Chapter 
3.2.) If desired, the user can identify that the area returned in 
response to a user file request is a VSWA, rather than an FIOA or FWA, 
by testing label VSWAID for a zero condition using mask VSWAM. 
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The user must code an EQU statement to set up a base register for the 
VSWA, equating the label VSWABAR to a general-purpose register i After a 
VSWA is acquired by CICS/VS in response to a DFHFC macro instruction 
using locate mode I/O, the user must establish addressability for the 
VSWA prior to any reference to that area. The following is an example 
of the coding required; it includes the optional test for VSWA 
identification : 

VSWABAR EQU 7 

COPY DFHVSWA 



L VSWABAR, TCAFCAA 

TM VSWAID,VSWAM WAS VSWA RETURNED? 

BZ GOTVSWA YES 



TRANSIENT DATA INPUT AREA (TDIA) 

The statement 

COPY DFHTDIA 

copies the symbolic storage definition for the CICS/VS system section of 
the intrapartition TDIA. This storage definition should precede the 
user's defined layout of the message area used for data obtained from an 
intrapartition destination by means of a DFHTD TYPE=GET macro 
instruction. (See "Acquire Queued Data (TYPE=GET)" in Chapter 5.6.). 
The user must code an EQU statement to set up a base register for the 
TDIA, equating the label TDIABAR to a general— purpose register. The 
user must also establish addressability for the TDIA following a DFHTD 
macro instruction. The following is an example of the coding required: 

TDIABAR EQU 9 

COPY DFHTDIA 

NAME DS CL20 

STREET DS CL20 



TDIABAR ,TCATDAA 



TRANSIENT DATA OUTPUT AREA (TDOA ) 

The statement 

COPY DFHTDOA 

copies the symbolic storage definition for the CICS/VS system section of 
the intrapartition TDOA* This storage definition should precede the 
user's defined layout of the message area for transient data to be 
directed to an intrapartition or extrapartition destination by means of 
a DFHTD TYPE=PUT macro instruction. (See "Dispose of Data (TYPE=PUT) " 
in Chapter 5.6.) 

The user must code an EQU statement to set up a base register for the 
TDOA, equating the label TDOABAR to a general— purpose register. The 
address of the data to be output (including the four— byte length field 
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in the case of variable— length records) must be given to transient data 
control either through the TDADDR operand of the DFHTD macro instruction 
or by placing it in TCATDAA. The following is an example of the coding 
reguired: 



TDOABAR 


EQU 


9 




COPY 


DFHTDOA 


TIME 


DS 


CL4 


DATE 


DS 


PL3 


INTERM 


DS 


CL4 


OUTTERM 


DS 


CL4 



DFHSC TYPE=GETMAIN,CLASS=TRANSDATA,NUMBYTE=19 
L TDOABAR, TCASCSA 



DFHTD TYPE=PUT ,DESTID=POST, TDADDR=TDOAVRL 

TDOAVRL is a name associated with the first byte of the output 
message (LL#Jrf for variable— length records). 



TEMPORARY STORAGE INPUT/OUTPUT AREA (TSIOA) 



The statement 

COPY DFHTSIOA 

copies the symbolic storage definition for the CICS/VS system section of 
the TSIOA* This storage definition should precede the user*s defined 
data fields. The user must code an EQU statement to set up a base 
register for the TSIOA, eguating the label TSIOABAR to a general— purpose 
register* The address of the data, which always includes a length field 
(LL#Jrf) for temporary storage must be given to temporary storage control 
either through the TSDADDR operand of the DFHTS macro instruction or by 
placing it in TCATSDA* The following is an example of the coding 
reguired: 

TSIOABAR EQU 6 

COPY DFHTSIOA 

PAGENO DS PL2 

TITLE DS CL30 

LINE1 DS CL70 

1 

* 

DFHTS TYPE=GET 

L TSIOABAR, TCATSDA 

SH TSIOABAR, =H»8» 

Upon execution of the DFHTS TYPE=GET macro instruction, CICS/VS 
returns the address of the data portion (LLjrf>5 field) of the temporary 
storage record which is read in TCATSDA* To establish addressability to 
the TSIOA (that is, to use the DFHTSIOA DSECT) , the application program 
must subtract eight from this address to point to the storage accounting 
field of the storage area acguired by CICS/VS. If the TSDADDR operand 
is included in the DFHTS TYPE=GET macro instruction, this is not 
reguired i 
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STORAGE ACCOUNTING AREA (SAA) 

The statement 

COPY DFHSAADS 

copies the symbolic storage definition for the SAA. This storage 
definition should precede the user's defined layout of a unique work 
area that is used within the application program. The user must code an 
EQU statement to set up a base register for the SAA, equating the label 
SAACBAH to a general— purpose register* The following is an example of 
the coding required: 

SAACBAR EQU 9 

COPY DFHSAADS 

SYMBLA EQU * 

NAME DS CL50 

STREET DS CL15 

SYMBLB EQU *-SYMBLA 



DFHSC TYPE=GETMAIN,INITIMG=00,NUMBYTE= SYMBLB, 
CLASS=USER 



SAACBAR, TCASCSA 



Having copied the symbolic storage definition for the SAA, the 
application program can specify a DFHSC TYPE=GETMAIN instruction 
requesting CICS/VS storage control to obtain main storage for use by the 
program. The address returned by CICS/VS in TCASCSA should be moved to 
SAACBAR, the base address register for the SAA. 



JOURNAL CONTROL AREA (JCA) 

The statement 

COPY DFHJCADS 

copies the symbolic storage definition for the CICS/VS system section of 
the journal control area (JCA) and must be present in all programs 
requesting journal services. (See "Journal Control", Chapter 7.5.) The 
user must code an EQU statement to set up a base register for the JCA, 
equating the label JCABAR to a general— purpose register* The following 
is an example of the coding required: 

JCABAR EQU 9 

COPY DFHJCADS 

A JCA is acquired by means of a DFHJC TYPE=GETJCA macro instruction. 
Addressability to the JCA is automatically provided through the macro 
expansion, which loads the JCA address into JCABAR. 
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Example of CICS/VS Assembler-language Application Program 

Figure 2 a 2— 1 is an Assembler— language program written to run under 
CICS/VS- The program asks a question of the terminal operator, receives 
a reply, dynamically acquires some storage, and sends the operator's 
message back to the terminal* In effect, an echo test is performed. 
(The line numbers in the figure are not part of the program.) 



01 


BASER E6 


BQU 


2 




02 


TCTTEAR 


EQU 


11 




03 


TI0A6AR 


EQO 


10 




04 




COPY 


DFHCSADS 




05 




COPY 


DFHTCADS 




06 


LENGTH 


DS 


H 




07 


MESSAGE 


DS 


CL32 




08 




COPY 


DFHTCTTE 




09 




COPY 


DFHTIOA 




10 


MESSG 


DS 


CL32 




11 




CSECT 






12 




BALR 


BASEREG,0 




13 




USING 


*,BASEREG 




14 




L 


TCTTEAR, TCAFCAAA 




15 




L 


TIOABAR,TCTTEDA 




16 




MVC 


MESSG, =C« ENTER MESSAGE TO BE 


ECHOED ■ 


17 




MVC 


TIOATDL, =H» 26 • 




18 




DPHTC 


TYPE= (WRITE, READ, WAIT, ERASE) 




19 




L 


TIOABAR,TCTTEDA 




20 




MVC 


LENGTH, TIOATDL 




21 




MVC 


MESSAGE, MESSG 




22 




DFHSC 


TYPE=GETMAIN, 




23 






CLASS=TERMINAL, 




24 






NUMBYTE=32 




25 




L 


TIOABAR,TCASCSA 




26 




ST 


TIOABAR,TCTTEDA 




27 




MVC 


MESSG, MESSAGE 




28 




MVC 


TIOATDL, LENGTH 




29 




DFHTC 


TYPE=WRITE 




30 




DFHPC 


TYPE=RETURN 




31 




END 







Figure 2i2— 1* Example of CICS/VS Assembler— Language Application Program 

A discussion of the significance of each of the lines of Figure 2.2—1 
follows. 
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Line Number Description 

01 Assigns base register for program. 

02—03 Assigns base registers for TCTTE and 

TIOA symbolic storage definitions * 
04—05 Copies CSA and TCA symbolic storage 

definitions. 
06—07 Defines fields in TWA as save areas to 

provide for quasi— reenterability* 
08—09 Copies TCTTE and TIOA symbolic storage 

definitions. 
10 Defines message area in TIOA. 

11—13 Begins program; establishes addressability 

for program. 

14 Establishes addressability for TCTTE. 

15 Establishes addressability for TIOA. 

16 Moves message to output area of TIOA. 

17 Moves length of message to data length 

field of TIOA* 

18 CICS/VS macro instruction that writes message 

to terminal, waits for operator" s reply, 

and reads operator *s reply* 

19 Establishes addressability for new TIOA, 

using address in TCTTE. 

20—21 Saves the message and the length of the 

message in the TWA save areas* 

22—24 CICS/VS macro that requests 32 bytes 

of terminal type storage* 

25 Establishes addressability for new TIOA 

(address of newly acquired storage area is 
in TCASCSA field of the TCA); 

26 Places address of new TIOA in TCTTE * 

27 Moves the message from TWA save area to 

new TIOA. 

28 Moves the message length to data length 

field of new TIOA. 

29 CICS/VS macro instruction that writes message 

to terminal. 

30 CICS/VS macro instruction that returns control 

to CICS/VS and terminates this task. 

31 Required for Assembler language. 
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The COBOL programmer must define storage for the CICS/VS control areas 
and any other storage areas reguired for the processing of the 
application program* This is done by using (1) the COPY statement in 
the Linkage Section of the Data Division to copy the symbolic storage 
definitions into the program and specify the names of the storage areas 
being defined, and (2) the MOVE statement in the Procedure Division to 
establish addressability by moving symbolic storage addresses from one 
location to another. 

The working storage section of a COBOL program should contain only 
data constants* Variable data should be placed in a TWA or in an area 
of storage acgUired by a DFHSC TYPE=GETMAIN macro instruction. (See 
"Obtain and Initialize Main Storage (TYPE=GETMAIN) " in Chapter 5.5.) 

The statement 

01 DFHBLLDS COPY DFHBLLDS* 

must be the first statement in the Linkage Section of the Data Division 
of an COBOL program that is run under CICS/VS. This statement copies 
the symbolic storage definition for the Linkage Section base locator 

(BLL) , which provides the means by which a COBOL program can address 
dynamically acquired CICS/VS storage areas. Included in this definition 
are the symbolic base addresses for the common system area (CSA) , common 
system area optional features list (CSAOPFL) , and task control area 

(TCA) * Symbolic storage definitions for these areas must be copied into 
every COBOL program. 

If other CICS/VS storage areas are needed, the COPY statement for the 
BLL must be followed immediately by statements of the form 

02 name PICTURE S9 (8) USAGE IS COMPUTATIONAL* 

where name is the symbolic base address used to locate a specific 
storage area. There must be one of these statements for each additional 
type of storage needed by the application program. Furthermore, these 
02— level statements must be coded in the same order as the corresponding 
01— level COPY statements coded subsequently to copy the symbolic storage 
definitions for the areas into the application program. 

If the user is going to communicate with the system by means of a 
terminal, a terminal input/output area (TIOA) and a terminal control 
table terminal entry (TCTTE) are needed* Assuming that only the 
reguired control areas (CSA and TCA) , a TIOA, and a TCTTE are needed for 
a particular application, the following example shows coding required in 
the linkage section of the Data Division: 

01 DFHBLLDS COPY DFHBLLDS* 

02 TCTTEAR PICTURE S9 (8) USAGE IS COMPUTATIONAL. 

02 TIOABAR PICTURE S9 (8) USAGE IS COMPUTATIONAL. 
01 DFHCSADS COPY DFHCSADS. 
01 DFHTCADS COPY DFHTCADS. 
01 DFHTCTTE COPY DFHTCTTE. 
01 DFHTIOA COPY DFHTIOA. 
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Storage Defined During Initialization 

During CICS/VS initialization, the common system area (CSA) is allocated 
as part of the CICS/VS nucleus* For each terminal that is to be used, a 
terminal control table terminal entry (TCTTE) must be included in the 
terminal control table (TCT) . The COBOL programmer must provide 
symbolic storage definitions for the CSA and TCTTE (if needed) as 
follows. 



COMMON SYSTEM AREA (CSA) 

The statement 

01 DFHCSADS COPY DFHCSADS* 

copies the symoolic storage definition for the CSA. Addressability for 
the CSA is included. 

If CICS/VS is generated to include a common work area (CWA) , a 
symbolic definition of that area must be included immediately following 
the COPY statement in the linkage section of the application program. 
The following is an example of the coding required: 

01 DFHCSADS COPY DFHCSADS. 
02 CWA. 

03 FIELD1 PIC X(4) . 



TERMINAL CONTROL TABLE TERMINAL ENTRY (TCTTE) 

The statement 

01 DFHTCTTE COPY DFHTCTTE. 

copies the symoolic storage definition for the TCTTE and must be present 
in all programs requesting communication with a terminal. The user must 
code the statement 

MOVE TCAFCAAA TO TCTTEAR. 

in the appropriate place in the Procedure Division to establish 
addressability for the TCTTE. TCAFCAAA contains the address of the 
facility that initiated the transaction. TCTTEAR is the terminal 
control table terminal entry address register. 
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Storage Defined During Execution 

During the execution of a task, the task control area (TCA) , the 
terminal input/output area (TIOA) , and other storage areas reguired by 
the task are allocated by CICS/VS storage management upon reguest from 
either the application program or CICS/VS* Symbolic storage definitions 
for these storage areas must be provided as follows* 



TASK CONTROL AREA (TCA) 

The statement 

01 DFHTCADS COPY DFHTCADS. 

copies the symbolic storage definitions for the CSA optional features 
list and the TCA. The user must code the statement 

MOVE CSACDTA TO TCACBAR. 

and can optionally code the statement 

MOVE CSAOPFLA TO CSAOPBAR. 

at the appropriate place in the Procedure Division to establish 
addressability for the TCA and the CSA optional features list. CSACDTA 
contains the address of the storage area obtained for the TCA (the 
common system area currently dispatched task address) . This address is 
stored in TCACBAR, the TCA control base address register. 

If the application program requires the use of a transaction work 
area (TWA) , the record layout of the TWA must be defined immediately 
following the COPY statement in the linkage section of the application 
program. The following is an example of the coding reguired: 

01 DFHTCADS COPY DFHTCADS. 
02 TWA PIC X(40) . 



TERMINAL INPUT/OUTPUT AREA (TIOA) 

The statement 

01 DFHTIOA COPY DFHTIOA* 

copies the symbolic storage definition for the CICS/VS system section of 
the TIOA and must be present in all programs that use terminal input 
records or that provide output records to a terminal. The following is 
an example of the coding required to define the record (s) in the TIOA: 

01 DFHTIOA COPY DFHTIOA. 
02 TRANS ID PIC XXXX * 
02 TIOAMSG PIC X (20 ) * 
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The user must establish addressability for the TIOA in the Procedure 
Division by coding in the appropriate place either the statement 

MOVE TCTTBDA TO TIOABAR* 

or the statement 

MOVE TCASCSA TO TIOABAR . 

The former statement is used to establish addressability to a TIOA 
acquired by CICS/VS during execution for data entered from a terminal. 
The latter statement is used to establish addressability for a new TIOA 
acquired by a DFHSC TYPE=GETMAIN macro instruction and should be coded 
immediately following that macro instructions 



PILE INPUT/OOTPUT AREA (FIOA) 



The statement 

01 DFHPIOA COPY DFHFIOA. 

copies the symbolic storage definition for the CICS/VS system section of 
the FIOA and must be present in all programs requesting a read of an 
unblocked record without updating or segmenting, or a read of blocked 
records without deblocking. If desired, the user can identify that the 
area returned in response to a file request is an FIOA, rather than an 
FWA or VSWA, by testing FIOAM. If data is retrieved using the Indexed 
Sequential Access Method (ISAM) under CICS/OS/VS, a 16-byte filler must 
be defined prior to the user's data definition. The following is an 
example of the coding required to define records in the FIOA: 



01 DFHFIOA COPY DFHFIOA* 
02 FILLER PIC X(16) . 
02 KEYF PIC X (6) * 
02 NAME PIC X(20) * 
02 FIOAREC PIC X(74) * 



NOTE OS/VS ISAM FILLER 



The user must code the statement 

MOVE TCAFCAA TO FIOABAR. 

prior to any reference to the FIOA following a DFHFC macro instruction 
in the Procedure Division to establish addressability for the FIOA. 

To identify the area returned as an FIOA, the following instruction 
can be used: 



IF FIOAM 

THEN GO TO GOTFIOA* 
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PILE WORK AREA (FWA) 

The statement 

01 DFHFWADS COPY DFHFWADS. 

copies the symbolic storage definition for the CICS/VS system section of 
the FWA and must be present in all programs performing file operations 
with the exception of a "read without update" from an unblocked, 
unsegmented data set* If desired, the user can identify the area 
returned in response to a file request as an FWA, rather than an FIOA or 
VSWA, by testing FWAM. The following is an example of the coding 
required to define records in the FWA: 

01 DFHFWADS COPY DFHFWADS. 
02 KEYF PIC X(6) . 
02 NAME PIC X (20) . 
02 FWAREC PIC X (24) . 



The user must code the statement 

MOVE TCAFCAA TO FWACBAR . 

prior to any reference to the FWA following a DFHFC macro instruction in 
the Procedure Division to establish addressability for the FWA. 

To identify the area returned as an FWA, the following instruction 
can be used: 

IF FWAM 

THEN GO TO GOTFWA . 



VSAM WORK AREA (VSWA) 

The statement 

01 DFHVSWA COPY DFHVSWA . 

copies the symbolic storage definition for the CICS/VS system section of 
the VSAM work area and must be present in all programs using VSAM locate 
mode I/O. (See "Direct Retrieval (VSAM Locate Mode)" in Chapter 3.2.) 
If desired, the user can identify that the area returned in response to 
a file request is a VSWA, rather than an FIOA or FWA, by testing VSWAM. 
The user must code the statement 

MOVE TCAFCAA TO VSWABARi 

prior to any reference to the VSWA acquired by CICS/VS in response to a 
DFHFC macro instruction using locate mode I/O. 

To identify the area returned as a VSWA, the following instruction 
can be used: 

IF VSWAM 

THEN GO TO GOTVSWA. 
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TRANSIENT DATA INPUT AREA (TDIA) 

The statement 

01 DPHTDIA COPY DPHTDIA. 

copies the symbolic storage definition for the CICS/VS system section of 
the intra partition TDIA and must be present in all programs requiring a 
message area for transient data obtained by issuing a DFHTD TYPE=GET 
macro instruction that refers to an intrapartition destination. (See 
"Acquire Queued Data (TYPE=GET) " in Chapter 5*6.) The following is an 
example of the coding required to define records in the TDIA: 

01 DFHTDIA COPY DFHTD IA. 
02 MESSAGE PIC X (25) . 

The user must code the statement 

MOVE TCATDAA TO TDIABAR* 

prior to any reference to the TDIA following a DFHTD macro instruction 
in the Procedure Division to establish addressability for the TDIA* 



TRANSIENT DATA OUTPUT AREA (TDOA) 

The statement 

01 DFHTDOA COPY DFHTDOA . 

copies the symbolic storage definition for the CICS/VS system section of 
the intrapartition TDOA and should be present in all programs issuing a 
DFHTD TYPE=PUT macro instruction to provide transient data as output. 
(See "Dispose of Data (TYPE=PUT)" in Chapter 5.6.) The following is an 
example of the coding required to define records in the TDOA: 

01 DFHTDOA COPY DFHTDOA. 
02 MESSAGE PIC X (20 ) * 

The user must code the statement 

MOVE TCASCSA TO TDOABAR . 

prior to any reference to the TDOA following a DFHSC macro instruction 
in the Procedure Division to establish addressability for the TDOA. 



TEMPORARY STORAGE INPUT/OUTPUT AREA (TSIOA) 

The statement 

01 DFHTSIOA COPY DFHTSIOA. 

copies the symbolic storage definition for the CICS/VS system section of 
the TSIOA and should be present in all programs using temporary storage. 
The following is an example of the coding required to define records in 
the TSIOA: 
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01 DFHTSIOA COPY DFHTSIOA. 
02 DATA PIC X(10) . 

To establish addressability for the TSIOA, the user must code the 
statements 

MOVE TCATSDA TO TSIOABAR. 
SUBTRACT 8 PROM TSIOABAR. 

if the request is a GET or GETQ from temporary storage and the TSDADDR 
operand is not specified. The subtraction of eight ensures that 
TSIOABAR points to the storage accounting field (that is, to the 
beginning) of the storage area acquired by CICS/VS. The user must code 
the statement 

MOVE TCASCSA TO TSIOABAR. 

if an I/O area has been acguired during execution* In the case of a POT 
or PUTQ, the symbolic address of the data is located at TSIOAVRL* 
Either statement must appear in the appropriate place in the Procedure 
Division of the COBOL program. 



STORAGE ACCOUNTING AREA (SAA) 

The statement 

01 DFHSAADS COPY DFHSAADS. 

copies the symbolic storage definition for the SAA. This storage 
definition should precede the definition of user storage acquired 
through the DFHSC TYPE=GETMAIN,CLASS=USER macro instruction* The 
following is an example of the coding required to define records in the 
SAA: 

01 DPHSAADS COPY DFHSAADS. 
02 NAME PIC X(20) . 
02 SAAREC PIC X (10) . 



The user must code the statement 

MOVE TCASCSA TO SAACBAR* 

prior to any reference to the SAA following a DFHSC macro instruction in 
the Procedure Division to establish addressability for the SAA. 



JOURNAL CONTROL AREA (JCA) 

The statement 

.01 DFHJCADS COPY DFHJCADS. 

copies the symbolic storage definition for the CICS/VS system section of 
the journal control area (JCA) and must be present in all programs 
requesting journal services. (See "Journal Control", Chapter 7.5.) 
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A JCA is acquired by means of a DFHJC TYPE=GBTJCA macro instruction. 
Addressability to the JCA is provided automatically through the macro 
expansion, which loads the address of the area into JCABAB. 



Additional Guidelines. 

If the object of an OCCURS DEPENDING ON clause is defined in the linkage 
section, special consideration is required to ensure that the correct 
value is used at all times. In the following example, FIELD-COUNTER is 
defined in the linkage section. The MOVE FIELD-COUNTER TO FIELD-COUNTER 
statement is needed to ensure that unpredictable results do not occur 
when referencing DATA. 

LINKAGE SECTION. 

01 DFHFWADS COPY DFSFWADS. 



02 FIELD-COUNTER PIC 9 (4) COMP. 

02 FIELDS PIC X (5) OCCURS 1 TO 5 TIMES 

DEPENDING ON FIELD-COUNTER. 
02 DATA PIC X (20) . 



PROCEDURE DIVISION 



DFHFC TYPE=GET, etc. 

MOVE TCAFCAA TO FHACBAR. 

MOVE FIELD-COUNTER TO FIELD-COUNTER. 

MOVE DATA TO TWA-FIELD. 

The MOVE statement referring to FIELD-COUNTER causes COBOL to 
reestablish the value it uses to compute the current number of 
occurrences of FIELDS and ensures that it can correctly determine the 
displacement of DATA. 

If an area greater than 4096 bytes is defined in the linkage section, 
special considerations arise. An additional 02— level statement under 
DFHBLLDS and an ADD statement following the MOVE statement to establish 
addressability to the area are required for each additional 409 6 bytes. 
For example, if a file work area (FHA) exceeds 4096 bytes, the following 
code can be used* 
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LINKAGE SECTION. 

01 DFHBLLDS COPY DFHBLLDS. 



02 PWACBAR PIC S9 (8) COMP 
02 FWABR1 PIC S9 (8) COHP 



01 DFHFWADS COPY DFHFWADS. 
02 FIELD1 PIC X(4000). 
02 FIELD2 PIC X(1000). 
02 FIELD 3 PIC X (400) . 



PROCEDURE DIVISION. 



DFHFC TYPE=GET, 



MOVE TCAFCAA TO FWACBAR. 

ADD 4096 TO FWACBAR GIVING FWABR1. 

If the size of the COBOL working storage is close to, or greater than 
64K then execution errors may occur. 

If an application program is to be compiled for execution under 
CICS/OSAS using the full COBOL V4 Compiler (5734-CB2) , the OS/VS COBOL 
Compiler (5740— CB1) with the optimization feature, or the DOS/VS COBOL 
Compiler (5746-CB1) with the optimization feature, a special translator 
control statement must be inserted at appropriate places within the 
program to ensure addressability to a particular area defined in the 
linkage section* This control statement has the form: 

SERVICE RELOAD fieldname. 

where fieldname is the symbolic name of a specific storage area, and is 
also defined in an 01— level statement in the linkage section. The first 
four statements of the Procedure Division must be: 

SERVICE RELOAD DFHBLLDS* 
SERVICE RELOAD DFHCSADS . 
MOVE CSAOPFLA TO CSAOPBAR* 
SERVICE RELOAD CSAOPFL. 

Statements such as: 

MOVE TCAFCAAA TO TCTTEAR * 
SERVICE RELOAD DFHTCTTE. 



or 



SUBTRACT 8 FROM TCASCSA GIVING TSIOABAR. 
SERVICE RELOAD DFHTSIOA * 
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can be used to establish addressability for a particular storage area. 
(Note that the SERVICE RELOAD statement must be used following each 
statement which modifies addressability to an area defined in the 
linkage section, that is, whenever an address is moved to a field named 
in an 02— level statement under 01 DFHBLLDS or the address in the 02— 
level statement is changed in any way.) 

To establish addressability to the TCA, the following statements must 
be coded: 

MOVE CSACDTA TO TCACBAR . 
SERVICE RELOAD DFHTCA. 

Note that the RELOAD statement specifies DFHTCA, not DFHTCADS* 

Certain COBOL features cannot be used in an application program to be 
run under CICS/VS. Generally, these features are replaced by CICS/VS 
servicesi They are identified under "Restrictions" in Part 1* 
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Example of CICS/VS COBOL Application Program 

Figure 2i3— 1 is a COBOL program written to run under CICS/VS* The 
program asks a guestion of the terminal operator, receives a reply, 
acquires storage, and sends the operator's message back to the terminal. 
In effect, an echo test is performed. (The line numbers in the figure 
are not part of the program.) 

01 IDENTIFICATION DIVISION. 

02 PROGRAM-ID. 

03 'CBLSPRB*. 

04 ENVIRONMENT DIVISION. 

05 DATA DIVISION. 

06 LINKAGE SECTION. 

07 01 DFHBLLDS COPY DFHBLLDS. 

08 02 TCTTEAR PIC S9 (8) COMP. 

09 02 TIOABAR PIC S9 (8) COMP. 

10 01 DFHCSADS COPY DFHCSADS. 

11 01 DFHTCADS COPY DFHTCADS. 

12 02 SAVE-LENGTH PIC S9 (8) COMP. 

13 02 SAVE-MESSAGE PIC X (36) . 

14 01 DFHTCTTE COPY DFHTCTTE. 

15 01 DFHTIOA COPY DFHTIOA . 

16 02 TIOAMSG PIC X(36). 

17 PROCEDURE DIVISION. 

18 MOVE CSACDTA TO TCACBAR. 

19 MOVE CSAOPFLA TO CSAOPBAR. 

20 MOVE TCAFCAAA TO TCTTEAR. 

21 MOVE TCTTEDA TO TIOABAR. 

22 MOVE •ENTER MESSAGE TO BE ECHOED* TO TIOAMSG. 

23 MOVE 26 TO TIOATDL* 

24 DFHTC TYPE= (WRITE, READ, WAIT) 

25 MOVE TCTTEDA TO TIOABAR. 

26 MOVE TIOATDL TO SAVE-LENGTH. 

27 MOVE TIOAMSG TO SAVE-MESSAGE. 

28 DFHSC TYPE=GETMAIN, * 

29 NDMBYTE=36, * 

30 CLASS=TERMINAL 

31 MOVE TCASCSA TO TIOABAR. 

32 MOVE TIOABAR TO TCTTEDA. 

33 MOVE SAVE-MESSAGE TO TIOAMSG. 

34 MOVE SAVE-LENGTH TO TIOATDL. 

35 DFHTC TYPE=WRITE 

36 DFHPC TYPE=RETURN 

37 GOBACK* 

Figure 2.3—1. Example of CICS/VS COBOL Application Program 
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A discussion of the significance of each of the lines of Figure 2*3—1 
follows. 



Line Number 

01-05 
06 
07 

08-09 

10 
11 

12-13 



14 
15 
16 
17 

18-21 



22 
23 

24 



25 

26 

27 

28-30 



31 

32 

33 
34 
35 

36 

37 



Description 

Reguired for COBOL. 
Start of linkage section. 

Copies symbolic storage definition for BLL; 
contains addresses of CICS/VS storage areas. 
Adds addresses for TCTTE and TIOA (reguired 
for statements 14 and 15) » 

Copies symbolic storage definition for CSA* 
Copies symbolic storage definitions for TCA 
and CSA optional features list * 
Defines save areas in TWA to ensure gua si- 
reenterability (SAVE-LENGTH and SAVE-MESSAGE 
are used to save operator's reply). 
Copies symbolic storage definition for TCTTE. 
Copies symbolic storage definition for TIOA. 
Defines message area in TIOA. 
Reguired for COBOL (start of Procedure 
Division) . 

Establishes addressability for TCA, CSA optional 
features list, TCTTE, and TIOA (CICS/VS establishes 
addressability for BLL and CSA) . 
Moves message to output area of TIOA* 
Moves length of message to data length field of 
TIOA* 

CICS/VS macro instruction that writes message to 
terminal, waits for operator's reply, and reads 
operator's reply * 

Establishes addressability for new TIOA using 
address in TCTTE. 
Saves length of message in TWA. 
Saves message in TWA. 

CICS/VS macro instruction that reguests 3 6 bytes 
of terminal storage (terminal storage is 
chained to terminal control table) . 
Establishes addressability for new TIOA (address 
of newly acguired storage area is in TCASCSA 
field of the TCA) . 

Places address of new TIOA in terminal control 
table* 

Moves message to output area (TIOA) * 
Moves length of message to output area (TIOA) . 
CICS/VS macro instruction that writes message to 
terminal. 

CICS/VS macro instruction that returns control 
to CICS/VS. 

COBOL statement that marks the end of the 
program. 
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The PL/I programmer must define storage for the CICS/VS control areas 
and other storage areas required for the processing of the application 
program* This is done by using a statement of the form 

^INCLUDE library (member) ; 

or 
96INCLUDE member; 

to (1) copy the appropriate symbolic storage definition into the 
application program at the place where the %INCLODE statement appears, 
and (2) specify the name of the storage area being defined. 

The PL/I source code provided by CICS/VS in response to S6INCLUDE 
statements is in the form of based structures. These structures 
describe the attributes of the storage areas and include pointer 
variables that provide the addresses of the actual locations in storage 
that the structures describe. 

All application programs must contain statements to copy the symbolic 
storage definitions for the common system area (CSA) and task control 
area (TCA) . The expansions of the CICS/VS macro instructions used in an 
application program refer to fields within these areas, so their 
locations must be identified. Whether additional storage definitions 
must be copied depends on the processing requirements (storage areas and 
macro instructions used) of the application program. The statements to 
copy the symbolic storage definitions must be in the order CSA, TCA, 
TCTTE, TIOA; this is because addressability for the last three areas 
mentioned depends on the previous area already having been copied. 

A PL/I program to be run under CICS/VS must contain the REENTRANT 
option in the first PROCEDURE statement to satisfy the CICS/VS 
requirement that code be quasi— reenterable. See "Programming Techniques 
and Restrictions" in Part 1 for a list of PL/I features that cannot be 
used. 



Storage Defined During Initialization 

During CICS/VS initialization, the common system area (CSA) is allocated 
as part of the CICS/VS nucleus. For each terminal that is to be used, a 
terminal control table terminal entry (TCTTE) must be included in the 
terminal control table (TCT) . The PL/I programmer must provide symbolic 
storage definitions for the csa and TCTTE (if needed) as follows. 



COMMON SYSTEM ARES (CSA) 

The statement 

56INCLUDE DFHCSADS; 

copies the based structures that symbolically define the CSA and the CSA 
optional features list. Addressability for both areas is included. 
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If CICS/VS is generated to support a common work area (CWA) , coding 
such as the following must be provided immediately following the 
%INCLUDE DFHCSADS macro: 



DECLARE 1 DFHCSAWK BASED (CSACBAR) , 
2 CSAFILL CHAR (512) , 
2 USERLBL1 attributes. 



2 USERLBLn attributes; 



TERMINAL CONTROL TABLE TERMINAL ENTRY (TCTTE) 

The statement 

^INCLUDE DFHTCTTE; 

copies the based structure that symbolically defines the TCTTE and must 
be present in all programs requesting communication with a terminal. 
Addressability for the TCTTE is included. 



Storage Defined During Execution 

During execution of a task, the task control area (TCA), terminal 
input/output area (TIOA) , and other storage areas required by the task 
are allocated by CICS/VS storage management upon request from either the 
application program or CICS/VS. Symbolic definitions for these storage 
areas must be provided as follows. 



TASK CONTROL AREA (TCA) 

The statement 

^INCLUDE DFHTCADS ; 

copies the based structure that defines the TCA and establishes 
addressability . 

The latter part of the based structure consists of a DECLARE 
statement that is not terminated by a semicolon. The declaration of the 
TCA structure must be completed by supplying an ending (for example, a 
semicolon) or, if a transaction work area (TWA) is desired, by supplying 
further declaration i The following is an example of the coding 
required: 

^INCLUDE DFHTCADS; 
2 TWA CHAR (40); 
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TERMINAL INPUT/DUTPOT AREA (TIOA ) 

The statement 

XlNCLUDE DPHTIOA; 

copies the based structure that defines the CICS/VS system section of 
the TIOA and establishes addressability * This statement must be present 
in all programs that use terminal input records or that write output 
records to a terminal * The declaration of the TIOA structure must be 
completed by supplying further declaration of the input/output area, 
which could be merely a dummy element. An action that reguires a TIOA 
can be reguested* For example, a DFHSC TYPE=GETMAIN macro instruction 
to obtain storage for a TIOA for the application program* The following 
is an example of the coding reguired 

XINCLUDE DFHTIOA; 
2 NAME CHAR (20) , 
2 STREET CHAR (20); 

* 

1 
* 
DFHSC TYPE=GETMAIN, * 

NUMBYTE=40, * 

CLASS=TERMINAL 
TIOABAR=TCASCSA; /* TCASCSA FIELD OF TCA CONTAINS ADDRESS 
OF NEWLY ACQUIRED STORAGE */ 



For additional information about GETMAIN, see "Obtain and Initialize 
Main Storage (TYPE=GETMAIN) " in Chapter 5*5. 



FILE INPUT/OUTPUT AREA (FIOA ) 

The statement 

XINCLUDE DFHFIOA; 

copies the based structure that defines the CICS/VS system section of 
the FIOA and must be present in all programs reguesting a read of an 
unblocked record without updating or segmenting, or a read of blocked 
records without deblocking* If desired, the user can identify that the 
area returned in response to a file reguest is an FIOA, rather than an 
FWA or VSWA, by testing FIOAIND for a bit value of 01. The declaration 
of the FIOA must be completed, and addressability must be established 
for the FIOA using the statement 

FIOABAR=TCAFCAA; 

following the DFHFC macro instruction. If data is retrieved using the 
Indexed Seguential Access Method (ISAM) under CICS/OS/VS, a 16-byte 
filler must be defined prior to the use^s data definition. The 
following is an example of the coding reguired; it includes the optional 
coding for FIOA identification: 
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^INCLUDE DFHFIOA; 

2 FILL CHAR (16), /*OS/VS ISAM FILLER*/ 

2 NAME CHAR (20) , 
2 ADDR CHAR (20) ; 



FIOABAR=TCAFCAA; 

IF FIOAIND=»01 , B THEN GO TO GOTFIOA; 



FILE WORK AREA (FWA) 

The statement 

%INCLUDE DFHFWADS; 

copies the based structure that defines the CICS/VS system section of 
the FWA. This statement should precede a user— declared file record area 
when reading or updating an existing blocked or segmented record, when 
adding a new record to a data set, or when retrieving records using the 
browse technique. If desired, the user can identify that the area 
returned in response to a file request is an FWA, rather than an FIOA or 
VSWA, by testing FWAIND for a bit value of 11* The declaration of the 
FWA must be completed, and addressability must be established for the 
FWA using the statement 

FWACBAR=TCAFCAA; 

following a DFHFC macro instruction. The following is an example of the 
coding required; it includes the optional test for FWA identification: 

^INCLUDE DFHFWADS; 
2 NAME CHAR (20), 
2 ADDR CHAR (20) ; 



* 
FWACBAR=TCAFCAA; 
IF FWAIND=»11»B THEN GO TO GOTFWA; 



VSAM WORK AREA (VSWA) 

The statement 

^INCLUDE DFHVSWA; 

copies the based structure that defines the CICS/VS system section of 
the VSAM work area and must be present in all programs using locate mode 
I/O* (See "Direct Retrieval (VSAM Locate Mode)" in Chapter 3.2.) If 
desired, the user can identify that the area returned in response to a 
file request is a VSWA, rather than an FIOA or FWA, by testing VSWAID 
for a bit value of 00000000* Addressability must be established for the 
VSWA using the statement 
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VSWABAR=TCAFCAA; 

following the DFHFC macro instruction using locate mode I/O which causes 
CICS/VS to acguire the VSWA. 

To identify the area returned as a VSWA, the following instruction 
can be used: 

IF VSWAID= , , B THEN GO TO GOTVSWA; 



TRANSIENT DATA INPUT AREA (TDIA) 

The statement 

^INCLUDE DFHTDIA; 

copies the based structure that defines the CICS/VS system section of 
the intrapartition TDIA and must be present in all programs requiring a 
message area for transient data obtained by issuing a DFHTD TYPE=G3T 
macro instruction that references an intrapartition destination. (See 
"Acquire Queued Data (TYPE=GET) " in Chapter 5*6.) The declaration of the 
TDIA must be completed, and addressability must be established for the 
TDIA using the statement 

TDIABAR=TCATDAA; 

following a DFHTD macro instruction* The following is an example of the 
coding required: 

^INCLUDE (DFHTDIA); 
2 MSG CHAR (40) ; 



TDIABAR=TCATDAA; 



TRANSIENT DATA OUTPUT AREA (TDOA) 

The statement 

^INCLUDE DFHTDOA; 

copies the based structure that defines the CICS/VS system section of 
the intrapartition TDOA and should be present in all programs issuing a 
DFHTC TIPE=PUT macro instruction to provide transient data as output. 
(See "Dispose of Data (TYPE=PUT) " in Chapter 5.6.)* The declaration of 
the TDOA must be completed, and addressability must be established for 
the TDOA using the statement 

TDOABAR=TCASCSA; 

following a DFHSC macro instruction. The following is an example of the 
coding required: 
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^INCLUDE DPHTDOA; 
2 TIME CHAR (2), 
2 DATA CHAR (3) , 
2 INTERM CHAR (4) , 
2 OUTTERM CHAR (4) ; 



DFHSC TYPE=GETMAIN, * 

NUMBYTE=XX, * 

CLASS=USER 

TDOABAR=TCASCSA; 



TEMPORARY STORAGE INPUT/OUTPUT AREA (TSIOA) 

The statement 

XINCLUDE DFHTSIOA; 

copies the based structure that defines the CICS/VS system section of 
the TSIOA and must be present in all programs using temporary storage. 
The declaration for the TSIOA must be completed* If the reguest is a ' 
GET or GETQ from temporary storage and the TSDADDR operand is not 
specified, addressability must be established for the TSIOA using coding 
such as: 

DCL TSIOABAA FIXED BIN (31) BASED (TSIOABAB) ; 
TSIOABAR=TCATSDA ; 
TSIOABAB=ADDR (TSIOABAR) ; 
TSIOABAA=TSIOABAA - 8; 

The subtraction of eight ensures that TSIOABAA points to the storage 
accounting field (that is, to the beginning) of the storage area 
acguired by CICS/VS* The statement 

TSI0ABAR=TCASCSA; 

must be coded if the I/O area has been acguired during execution* In 
the case of a POT or PUTQ, the symbolic address of the data is located 
at TSIOAVRL* 



STORAGE ACCOUNTING AREA (SAA) 

The statement 

^INCLUDE DFHSAADS; 

copies the based structure that defines the SAA and must be present in 
all programs reguesting storage through use of the DFHSC 
TYPE=GETMAIN,CLASS=USER macro instruction* This statement must precede 
the definition of user storage* The declaration for the SAA must be 
completed, and addressability must be established for the SAA using the 
statement : 
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SAACBAR=TCASCSA; 
The following is an example of the coding required 



XINCLUDE DFHSAADS; 
2 MSG CHAR (40) ; 



DPHSC TYPE=GETMAIN, * 

NUMBYTE=60, * 

CLASS=USER 

SAACBAR=TCASCSA; 



JOURNAL CONTROL AREA (JCA) 

The statement 

KINCLUDE DPHJCADS; 

copies the based structure that defines the CICS/VS system section of 
the journal control area (JCA) and must be present in all programs 
requesting journal services! (See "Journal Control", Chapter 7.5.) 

A JCA is acquired dynamically by means of a DPHJC TYPE=GETJCA macro 
instruction i Addressability to the JCA is provided automatically 
through the macro expansion, which loads the address of the area into 
JCABAR. 
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Example of CICS/VS PL/I Application Program 

Figure 2i4— 1 is a PL/I program written to run under CICS/VS. The 
program asks a question of the terminal operator, receives a reply, 
acquires storage, and sends the operator's message back to the terminal. 
In effect, an echo test is performed. (The line numbers are not part of 
the program. ) 

01 PL1PR0G: PROCEDURE OPTIONS (MAIN, REENTRANT) ; 

02 ^INCLUDE DFHCSADS; 

03 ^INCLUDE DPHTCADS; 

04 2 SAVE_LENGTH BINARY FIXED (15) , 

05 2 SAVE_MSG CHAR (36); 

06 56INCLODE (DFHTCTTB) ; 

07 XINCLODE (DFHTIOA) ; 

08 2 TIOAMSG CHAR (36); 

09 TIOAMSG= , ENTER MESSAGE TO BE ECHOED*; 

10 TI0ATDL=26; 

11 DFHTC TYPE= (WRITE, READ, WAIT) 

12 TIOABAR=TCTTEDA; 

13 SAVE_LENGTH=TIOATDL; 

14 SAVE_MSG=TIOAMSG; 

15 DFHSC TYPE=GETMAIN, * 

16 NUMBYTE=36, * 

17 CLASS=TERMINAL 

18 TIOABAR=TCASCSA; 

19 TCTTEDA=TIOABAR; 

20 TIOAMSG=SAVE MSG; 

21 TIOATDL=SAVE~LENGTH; 

22 DFHTC TYPE=WRITE 

23 END; 

Figure 2.4—1. Example of CICS/VS PL/I Application Program 

A discussion of the significance of each of the lines of Figure 2.4—1 
follows. 
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Line Number Description 

01 Required for PL/I. REENTRANT option specified to meet 
requirement of CICS/VS that code be guasi— reenterable . 

02 Copies symbolic storaqe definitions for CSA and CSA 
optional features list and establishes addressability. 

03 Copies symbolic storage definition for TCA and 
establishes addressability s 

04—05 Defines the TWA and terminates the DECLARE statements 
SAVE_MSG and SAVE_LENGTH are used to preserve the 
operator's reply. 

06 Copies symbolic storage definition for TCTTE and 
TCTTE and establishes addressability. 

07 Copies symbolic storage definition for TIOA and 
establishes addressability. 

08 Describes I/O area for terminal message and terminates 
the DECLARE statements 

09 Places message to be sent to operator in the TIOA. 

10 Places the message length in the terminal data length 
field of the TIOA. 

11 CICS/VS macro instruction that writes the message to the 
terminal, waits for, and reads, the operator's reply. 

12 Reestablishes addressability for the TIOA using address 
in the TCTTE. 

13—14 Saves the operator's message and its length in the TCA. 
15—17 CICS/VS macro instruction that requests 36 bytes of 

terminal storage (terminal storage is chained to the TCT) . 

18 Establishes addressability for the new TIOA (address of 
the newly acquired storage is in TCASCSA) . 

19 Places address of new TIOA in terminal control table. 
20—21 Moves message and length of message to output area (TIOA). 

22 CICS/VS macro instruction that sends operator's message 
back to the terminal* 

23 PL/I statement that marks the end of the procedures 



Chapter 2.4. Storage Definition — PL /I 67 



Part 3. Data Base Operations 



69 



Chapter 3.1. Introduction to Data Base Operations 



The following two chapters in this part are concerned with the control 
of files within a user data base. Two main methods are described: the 
direct handling of records by the file control macro instruction; and 
the indirect handling by the DL/I interface. 



File Control Macro Instruction 

Chapter 3.2 describes how an application program handles records in a 
user data base by means of the file control program. Records in the 
data base are operated on by the file control macro instruction (DFHFC) , 
according to the various TYPE operands; for example, records can be 
retrieved by the DFHFC TYPE=GET macro instruction. 

The file control program can be used only with direct— access data 
sets. Sequential data sets are handled by the transient data program 
and the DFHTD macro instruction, as described in Chapter 5.6. 

An application program can also browse a data set in a user data base 
by means of the file control macro instruction. Browsing is defined as 
the retrieval of records in a direct -access data set, starting and 
ending at specified records, in ascending or descending sequence. 



DL/I Services 

Chapter 3.3 describes the macro instructions and calls available to a 
CICS/VS application program that enable that program to use a DL/I data 
base . 

The method of invoking DL/I differs for the two operating systems 
used with CICS/VS. For CICS/OS/VS, the DL/I interface is invoked by 
either a DL/I CALL statement or by a DFHFC macro instruction. For 
CICS/DOS/VS, however, the DL/I interface is invoked only by a DL/I CALL 
statement. 

DL/I is a general— purpose data base control system that executes in a 
virtual storage environment. When used online, it simplifies the task 
of creating and maintaining large data bases that are to be accessed by 
various application programs. For more information about DL/I, refer to 
the DL/I publications listed in the bibliography and to the CICS/VS 
System/Application Design Guide . 
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Chapter 3.2. File Control (DFHFC Macro Instruction) 



The file control program processes fixed— or variable— length, blocked or 
unblocked, undefined, or segmented records of a data set that is stored 
in a direct— access storage device. 

File control uses standard access methods of the host operating 
system, namely: 

• Direct Access Method (DAM) 

• Indexed Sequential Access Method (ISAM) 

• Virtual Storage Access Method (VSAM) 

Application programs can access DAM data sets on a logical record 
level, deblocking services being provided by file control. If an ISAM 
data set is converted to a VSAM data set organization, using VSAM data 
set conversion utilities, no alteration to application programs that 
access the data set is necessary, but the file control table (FCT) must 
be changed* Data sets on fixed block architecture (FBA) devices can be 
accessed by VSAM only* 

Through the file control macro instruction (DFHFC), an application 
program can perform file inquiry, that is, read a record from a data 
set; update a record in a data set; or add a record to a data set* In 
the last case the application program must obtain sufficient main 
storage for the record by means of the DFHFC TYPE=GBTAREA macro 
instruction. The application program can also release the main storage 
that has been acquired* For VSAM key— sequenced or relative— record data 
sets only, the DFHFC macro can be used to delete records, singly or in 
groups* 

General file— handling capabilities available to application programs 
include indirect access to data sets, handling of "duplicates" data 
sets, and use of segmented records* These capabilities are explained 
later in this chapter. 

All buffers and work areas needed for data set operations are 
acquired by file control in accordance with the data set descriptions 
supplied in the FCT by the system programmer. All data sets and all 
segment sets referred to in DFHFC macro instructions must have been 
defined in the FCT. The application programmer should work with the 
system programmer in setting up these data set descriptions. However, 
the application program need deal only with logical records; it is not 
directly involved with other characteristics of the data set. 

For a DAM or ISAM data set, all data is read into or written from one 
of two main storage areas: (1) a file input/output area (FIOA) or (2) a 
file work area (FWA) • An FIOA is required to handle records that are 
read-only, unsegmented, and unblocked* An FWA is required to handle 
records that are segmented, blocked, to be added, or to be updated. In 
addition, an FWA is always used in a browse operation. 

For a VSAM data set, all data is read into or written from an FWA 
with two exceptions: a locate mode read— only request for an unsegmented 
record, and when operating in ISAM compatibility mode* (ISAM 
compatibility mode is indicated by the system programmer specifying 
RECFORM= (UNBLOCKED) in the file control table entry for the data set.) 
In the first case, the address of the retrieved record, as it is 
positioned in the VSAM buffer, is made available to the application 
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program at VSWAREA within the VSWA. The record remains in the VSAM 
buffer, and must not be modified. In the second case, the retrieved 
record is moved to an FIOA for a read— only request for an unsegmented, 
unblocked record. A symbolic storage definition must be provided for 
this area (for example, an assembler— language DSECT) and addressability 
must be established to it* When operating in ISAM compatibility mode, a 
16-byte filler must be defined (for OS/VS only) prior to the user's data 
(as in normal ISAM mode) . 

CICS/VS permits the sharing of VSAM resources by means of the DFHFCT 
TYPE=SHRCTL system macro instruction as explained in the CIC S/VS System 
P rogrammer 's Reference Manual . When a task requires resources in 
several VSAM data sets at the same time and these data sets are sharing 
resources, the possibility of a lockout increases. 

New VSAM data sets, and existing ones that are to be reused, must be 
loaded with at least one record before a CICS/VS file control macro can 
be used for normal addition and update. This may be done either online 
by a CICS/VS application program or offline by a batch program. In the 
case of a CICS/VS program, certain restrictions must be observed; these 
are explained in the CICS/VS System Programmer's Reference Man ual. 

If an error occurs while accessing a VSAM data set, a DFHFC 
TYPE=RELEASE macro must be issued after the error has occurred* Failure 
to issue a TYPE=R3LEASE may result in a permanent wait. 

The user can determine which area (FIOA, FWA, or VSWA) is returned in 
response to a file request. Refer to Chapter 2.2, 2.3, or 2.4 
(depending on the programming language being used) for details. 

File control executes at the priority of the requesting program, 
under control of the TCA of the requesting program, saving and restoring 
registers from this TCA* The CICS/VS response to a request for file 
services can be checked as explained under "Test Response to a Request 
for File Services," later in this chapter* Control can be routed to any 
of various user— written exception— handling routines based on the outcome 
of the file operation. 

Parameter values must be specified, when using the file control macro 
instruction, in either of two ways: 

• By including the parameters in operands of the DFHFC macro 
instruction by which file services are requested, or 

• By coding instructions that place the parameter values in fields of 
the TCA prior to issuing the DFHFC macro instruction. 

The second of these approaches is provided to allow the application 
program to specify parameters which can only be determined during 
execution, for example, input messages from a terminal. 



Browsing 

The application program can browse a data set* This browsing is 
comparable to a visual, sequential search of a file. The file control 
macro instruction is used to specify a starting point for the browse, 
request each succeeding, or preceding record, reset the starting point 
for the browse (if desired) , and terminate the browse. 

The browse operations are requested by the appropriate TYPE operands 
of the DFHFC macro* The TYPE operands are SETL, GETNEXT, GETPREV, 
RESETL, and ESETL. The capabilities associated with each are summarized 

74 CICS/VS APR M (ML) 



below. Keyword operands to request checking of a CICS/VS response can 
be specified with these macro instructions as with other DPHFC macro 
instructions (see "Test Response to a Request for Pile Services," later 
in this chapter-) Specific operands for each macro instruction are 
discussed in detail at the end of the chapter. 

When accessing a VSAM data set, the browse facility can be used to 
perform random skip— sequential processing in a forward direction only* 
The following steps are required: 

1. Group several random requests into ascending key sequence. 

2. Issue a DFHFC TYPE=SETL macro instruction which finds the first 
required record. To achieve this, the record identification field 
pointed to by the RDIDADR operand should be initialized to the key 
of the required record. 

3. Prior to each DFHFC TYPE=GETNEXT macro instruction, place the key 
of the next required record into the record identification field. 

This procedure allows quick random access to a VSAM data set by 
reducing index search time. When the record having the highest key has 
been retrieved, an ESETL or RESETL should be issued to terminate or 
reset the operation. 

A browsing operation should always be terminated by issuing an ESETL 
macro, but will also be terminated by a normal or abnormal end of task. 



Segmented Records 

An optional feature of CICS/VS file management allows the user to create 
and define a data set containing segmented records* A segmented record 
is one in which the components of the record have been identified 
symbolically and then grouped according to some logical relationship 
such as function or frequency of use. 

The identifiable groups are called segments . A segment is one or 
more adjacent fields within a record. Some segments appear in all 
records (for example, segments containing identification or major record 
control fields) , while other segments apply to, and appear in, only 
certain records. If it is planned to use segmented records in a 
program, the structure and individual segments of the data set must have 
been defined in the file control table by the system programmer* The 
maximum number of segments allowed is 99. 

The following general rules apply to the use of segmented records: 

1* Segmented records can be used with VSAM, ISAM, or DAM data sets. 

2. Segmented records can be used with any record format (that is, 
fixed, fixed blocked, variable, undefined) but are primarily 
advantageous when processing variable— length records. 

3. A data set that contains segmented records cannot be an index data 
set in an indirect accessing hierarchy. The two CICS/VS features 
are mutually exclusive for any one data set . However, the primary 
data set in an indirect accessing hierarchy may contain segmented 
records if it is not defined also as an index data set. (See 
"Indirect Accessing" later in this chapter . ) 
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4. Every segment that may appear in a record, whether or not it 
actually exists in a particular record, must be defined in the file 
control table. 

5. The user must create and maintain the control information that 
governs the segments in a record. 

For further information on segmented records see the CICS/V S 
System/Application Design Guide . 



Alternate Indexing 

Alternate indexing, an optional data base feature in CICS/VS under VSAM, 
allows a data set to have more than one index* The second and 
subsequent indexes are called alternate indexes and these enable a data 
set to be accessed by one or more alternate paths. These alternate 
paths can be specified by multiple keys. 

Also, a data set with the alternate index feature can have two or 
more records with the same alternate key* To retrieve the first record 
with the same key the DPHFC TYPE=GET macro with the DUPKEY operand is 
sufficient* However, to continue retrieving the remaining records with 
the same key, a browse operation must be initiated. The DOPKEY operand 
also must be specified on the appropriate macro. The records will be 
retrieved in the order in which they were added to the data set, the 
duplicate key condition being raised for each record except the last* 
When changing to the browse operation, the first record will be 
retrieved twice, once by the TYPE=GET and once by the browse. 

Defining the alternate indexes as part of an update group will 
elimate the possibility of one or more indexes becoming invalid whenever 
the data set is updated* 



Indirect Accessing 

Indirect accessing, an optional data set feature in CICS/VS, provides 
for the use of cross— index data sets to access another data set. The 
data set that is accessed by an index data set is known as the primary 
(or target) data set. The user can include the search argument for an 
index data set in the identification of the primary data set. CICS/VS, 
using the user-defined index structure, carries out the search, 
involving as many levels (index data sets) as defined by the user, and 
ultimately retrieves the primary data set. 

The following general rules apply to indirect accessing: 

1* A primary data set can have any number of index data sets. This is 
useful when many cross references to a master record exist* 

2. Any data set can be both an index and a primary data set. The 
logical record content of any data base data set is user-nlef ined 
and constructed, and therefore may contain certain master record 
information as well as a search argument for another data set* 

3* There is no logical limit to the number of index levels (data sets) 
that the user may define in an index hierarchy. For example, data 
set A is an index to data set B, which is an index to data set C, 
and so on. 
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4. An index hierarchy can be any combination of VSAM, ISAM, and DAM 
data sets. 

5. An index data set cannot contain segmented records i The two 
CICS/VS features are mutually exclusive for any one data set. 
However, a primary data set can have segmented records if it is not 
defined also as an index data set. 

6. An index data set cannot reference more than one primary data set 
unless the index data set is multiply defined in the file control 
table. 

7. If the index data set is a BDAM data set, it cannot be defined as 
blocked. However, the primary data set can be defined as blocked 
BDAM. 



Figure 3-2—1 shows a simple two— level i 
accessing. The search begins with the ind 
primary data set being accessed (and from 
to the application program) is PARTNO. Th 
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Figure 3.2—1. Indirect Accessing (Two— Level Index) 

An installation must create and maintain all data sets in its data 
base, and define all data sets (both index and primary) in the file 
control table. Each data set, whether index and/or primary, is first 
described as a primary data set. That is, its basic physical 
characteristics (BLKSIZE, LRECL, KEYLEN, and so on) are defined so that 
CICS/VS file management can access it. If the data set is to be used as 
an index data set, the following information must also be specified: 

1. The primary data set for which this data set is an index. 

2. The location of the search argument, within the logical record of 
this data set, to be used for accessing the primary data set (or 
the next index data set) . 

If the user creates and defines an index hierarchy for indirect 
accessing, CICS/VS file management services any request requiring use of 
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tiiat hierarchy, provided the requesting application program adheres to 
the following general rules and considerations: 

1. The symbolic name of the first index data set to be searched in the 
retrieval process must be specified in the INDEX operand of the 
DFHPC macro instruction. This data set can be any index data set 
in a hierarchy of indexes, not necessarily the highest level index 
data set. 

2. The symbolic name of the primary data set from which data is to be 
ultimately retrieved and returned to the requesting program must be 
specified through the DATASET operand of the DFHFC macro 
instruction. Any number of intervening data sets can be used in 
the search; however, the user specifies only the first and the last 
data set. The user can limit a search to only a portion of an 
index hierarchy; that is, it is not necessary to search an entire 
index hierarchy, because the user can specify that the search begin 
at other than the highest— level index. Indexing levels cannot be 
omitted from within the hierarchical chain. 

3. The search argument to be used by CICS/VS file management to access 
the first referenced data set must be specified through the RDIDADR 
operand of the DFHFC macro instruction. This operand points to a 
record identification field containing a VSAM key or relative byte 
address, an ISAM key, or DAM block reference information. If 
multiple levels of index data sets are involved, CICS/VS file 
management acquires a search argument for the next data set from 
the logical record of each successive data set. 

When stepping through a series of index data sets, CICS/VS file 
management uses the record identification field (specified in the 
RDIDADR operand) to store the search argument for each successive data 
set to be searched. This field must be as large as the largest search 
argument that is likely to be used in any given retrieval operation. 

Figure 3*2—2 is an example of the above consideration in a three- 
level index hierarchy for indirect accessing. The search argument 
provided by the processing program is used to access the first index 
data set (CATLOG#) that provides the search argument for a second index 
data set (PARTNO) that provides the search argument for the primary data 
set (VENDOR) from which the data record is retrieved and returned to the 
application program. Since the search argument retrieved from the 
second index data set (PARTNO) is eight bytes in length (V000099 6) , the 
record identification field (RDIDADR) must be at least eight bytes in 
length, even though it initially contains only the five— byte search 
argument (CN222) for the first index data set. 
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Figure 3.2—2. Indirect Accessing (Three— Level Index) 



Duplicate Records 



An optional feature of the indirect accessing approach to data base 
retrieval is the capability to indicate that a search argument in an 
index data set, which normally refers to the primary data set, instead 
refers to a "duplicates" data set. The need for or use of duplicates 
data sets may best be described as follows. 

Assume that the application program reguires access to an index data 
set organized by street address to obtain the name of the occupant at 
that address. The occupant *s name is then used to access a primary data 
set organized by name. 

For single occupancy, no problem exists. However, if multiple 
occupancy is possible, the index data set cannot directly eguate a 
street address to a primary data set record. In this case, the search 
argument field in the index record must indicate that multiple occupants 
(duplicates) exist and that the search argument refers to a duplicates 
data set rather than the primary data set* 

CICS/VS file management retrieves the referenced record from the 
duplicates data set and returns it to the application program with a 
response code indicating a duplicate record. The duplicate record may 
contain further information, which the application program can use to 
more accurately retrieve the appropriate record from the primary data 
set. 

If an index data set is to indicate that there can be duplicate keys 
for entries in the primary data set to which it refers, this information 
must also be noted in the file control table entry which describes the 
index data set. The index data set record must contain a unigue one- 
byte duplicates indicator (user— defined) in the first byte of the search 
argument field. Care must be taken to ensure that this indicator is a 
unigue code; it cannot be the same as the first byte of a normal search 
argument for the primary data set. 

The rest of the search argument field contains the search argument 
used by CICS/VS file management to retrieve a record from the duplicates 
data set a This record may contain user— defined and user— constructed 
information that the application program can use to select the 
appropriate primary data set record. Figure 3.2—3 is an example of a 
search argument field in an index record that reflects duplicates: 
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Figure 3*2—3* Indirect Accessing (Search Argument Field) 

The search argument for the duplicates data set must meet the same 
search argument format requirements as a normal cross— index data set. 
The length of the search argument used to access a duplicates data set 
is one byte smaller than a normal search argument because of the 
duplicates indicator. 

Figure 3*2— 4 is an example of an index hierarchy that includes a 
duplicates data set. The application program begins the retrieval by 
accessing the index data set (PARTNAM) and ultimately accesses the 
primary data set (PARTNO) . The search argument (GISMO) provided by the 
application program is a valid one for the index data set (PARTNAM) , but 
it provides a record containing a duplicates flag. When the duplicates 
indicator is detected, CICS/VS file management uses the new search 
argument (from the PARTNAM data set) to access the duplicates data set 
(DUPLNAM), returning the duplicates record to the application program. 

In this example, the part name (GISMO) is not unique since there are 
several types of GISMOs in the part number (PARTNO) data set. The 
requesting program must provide qualifying data that indicates which 
GISMO is desired. 
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Figure 3.2—5 shows the message the application program might 
formulate to be routed to the inquiring terminal asking the terminal 
operator to make a choice. 




PART NAME REQUESTED HAS MULTIPLE ENTRIES 
PLEASE SELECT SPECIFIC PART NUMBER 

PART NAME DESCRIP PART NUMBER 
GISMO LARGE 9123 

MED 9872 

SMALL 9944 




Figure 3.2—5. Indirect Accessing (Message to Terminal) 

Once the terminal operator has made a selection, the program can make 
a direct retrieval from the primary (PARTNO) data set. 

If the index record in the example in Figure 3*2—4 had not contained 
a duplicates indicator, CICS/VS file management would have used the 
search argument to access the primary data set (PARTNO) and retrieve the 
requested data. 



Record Identification Field 



The record identification field is used by the application program to 
communicate to CICS/VS file control the identity, in the form of a key 
or address, of a specific record, or the starting point of a set of 
records, required in input/output operations. This field is identified 
by the RDIDADR operand of the DFHFC macro instruction. 

If multiple browse operations are performed concurrently by a single 
application program, a unique record identification field must exist for 
each operation. The application program must provide the storage area 
for the record identification field* Generally, this storage can be 
allocated within the transaction work area (TWA) of the task control 
area (TCA) , or some area acquired dynamically by the application 
program. Because CICS/VS application programs must be quasi- 
reenterable, it is not advisable to set up the record identification 
field within the application program. 

For an ISAM data set, the record identification field simply contains 
the key of the logical record. For CICS/OS/VS systems, the contents of 
the record identification field may have been changed following the 
addition of a new record when using ISAM; this point is worth 
considering in CICS/DOS/VS systems also, to avoid subsequent DOS to OS 
conversion difficulties* 

For a VSAM data set, the record identification field contains either 
the logical record key or the relative byte address of the desired 
record. If the generic key option is used, the first byte of the field 
must contain the key length, in binary, and the remainder of the field 
must contain the generic key. 

A partial key may be used as a search argument in a browse operation 
referring to either an ISAM or a VSAM data set. The ISAM partial key is 
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an implied generic key, recognized as such because of padding with 
binary zeros or blanks in insignificant positions of the key. In 
contrast, a VSAM generic key is defined to be a generic key, with its 
length explicitly specified in the first byte of the record 
identification field. The ISAM implied generic key applies only to 
browse operations. The VSAM— defined generic key can be specified in 
many DFHPC macro instructions. 

For a DAM data set, the record identification field structure is more 
complex. The application program must supply the block reference 
information, the physical key (if keyed data sets are being used) , and 
the deblocking argument (if blocked data sets are being used) . The 
record identification field is really a concatenation of three 
subfields, as follows: 

1. Block reference 

The block reference for the data set in the DAM block is specified 
by the RELTYPB operand of the DFHFCT TYPE=DATASET system macro and 
may be one of the following: 

a. Relative block (CICS/OS/VS only) three— byte binary 

(RELTYPE=BLK) 

b. Relative track and record — two— byte TT, one— byte R 
(RELTYPE=HEX) 

c* Relative track and record (zoned decimal format) six— byte 
TTTTTT, two-byte RR (RELTYPE=DEC) 

d. Actual address — eight-byte MBBCCHHR (RELTYPE omitted) 

Figure 3.2—6 shows examples of the four ways of specifying the block 
reference information for a DAM data set. 
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1 
i 

T 


T 


T 


R 


R 




| T T 


R 




| T T 


T 


1 

1 
j 


| M B 


B 


C 


C 


H 


H 


R 


1 



Relative block (OS/VS only) 
(three byte binary) 

Relative track and record 
(two byte hex, one byte hex) 

Relative track and record 
(zoned decimal) 

Actual address (eight bytes) 



Figure 3.2-5. Record Identification Field (Block Reference) 

2. Physical key 

The physical key is required only if the data set being accessed is 
written with recorded keys. This key must be the same length as 
specified in the BLKKEYL operand for the file control table entry 
which defines the data set. It must immediately follow the block 
reference information, which can be any of the above. 
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Figure 3-2—7 shows examples of the addition of the physical key for a 
DAM data set • 



Byte 





1 


2 


3 4 5 6 7 8 . . 




RELBLKt 


| KEY... (CICS/OS/VS only) 




T 


T 


R 


|KEY... 




T 


T 


T 


T T T R R | KEY... 

■ 




M 


B 


B 


C C H H R | KEY... 



Figure 3.2—7. Record Identification Field (Physical Key) 

3. Deblocking argument 

The deblocking argument is required only if the data set contains 
blocked records and specific logical records are to be retrieved 
from within a block* It is not mandatory that every physical 
record of a blocked data set be deblocked. If the application 
programmer does not specify a deblocking argument, an entire alock 
is read into an FIOA. The deblocking argument may be either a key 
or a relative record number. The user •s choice is specified in the 
RETMBTH (retrieval method) operand of the DFHFC macro instruction. 
If present, the deblocking argument must immediately follow the 
physical key (if present) or the block reference (if the physical 
key is not present) . 

If the deblocking argument is a key, it must be the same length as 
specified in the KEYLEN operand of the file control table entry 
which describes the data set. The key used for deblocking need not 
be the same size as the physical record key (BLKKEYL) . If the 
deblocking argument is a relative record number, it is represented 
by a one— byte binary number, with a value of zero representing the 
first logical record of a block. 

Figure 312—8 shows examples of the addition of a deblocking argument 
to the record identification field for a DAM data set. 
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(physical key = 6 bytes, deblocking key = 3 bytes) 



Byte 



12 3 



5 6 7 8 9 10 11 12 13 14 15 



RELBLK | RN | (CICS/OS/VS only) 



RELBLK | KEY | (CICS/OS/VS only) 

KEY 



| KEY 



I 



M B B 



H H 



R |RN| 



Search by relative block; 
deblock by relative record 

Search by relative block; 
deblock by key 

I Search by relative track 
' and record and key; 
deblock by key 

Search by actual address; 
deblock by relative record 



T R R | 



KEY 



I 



KEY | 



T R | KEY 



Search by zoned decimal 
relative track and record 
and key; deblock by key 

Search by relative track and 
record; deblock by key 



Figure 3.2—8. Record Identification Field (Deblocking Argument) 



DAM Data Sets 



Records in a nonkeyed DAM data set may be updated using either of two 
methods. One method is to issue a DFHFC TYPE=GET,TYPOPER=UPDATE to read 
the record, change the data in the FWA, and issue a DFHFC TYPE=P0T to 
physically update the record. This is the normal way that records are 
updated and should be used when portions of the record are to be changed 
and the actual contents of the record are unknown. 

An alternative method may be used when the contents of the record to 
be updated are known, or when the entire record is to be changed, 
regardless of its contents. A DFHFC TYPE=GETAREA macro instruction is 
used to acquire an FHA, the record is built in the FWA, and a DFHFC 
TYPE=PUT,TYPOPER=UPDATE is issued to write the data at the location 
specified in the record identification field, destroying whatever was 
previously recorded at that location* This approach requires that both 
DAH update and DAM add capabilities be generated into the CICS/VS file 
control program (see the CICS/VS System Programmer's Reference Manu al) . 
Automatic logging must not be specified for files to be updated by this 
method. 

When adding new records to a DAM data set, the following 
considerations and restrictions apply: 
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1. When adding undefined or variable— length records (keyed or 
nonkeyed) , the application programmer must indicate the track on 
which each new record is to be added* If space is available on the 
track, the new record is written following the last previously 
written record, and the record number is placed in the "R" portion 
of the record identification field of the record. The track 
specification may be in any of the acceptable formats except 
relative block a If zoned decimal relative format is used, the 
record number is returned as a two— byte zoned decimal number in the 
seventh and eighth positions of the record identification field. 

In the CICS/DOS/VS system, an attempt to add a variable— length or 
undefined record is limited to the single track specified by the 
application programmer. If insufficient space is available on that 
track, a "no space available" error is returned, and the 
application programmer may then try to add the record on another 
track. Under these circumstances, the record is returned to the 
application program in an FWA, the address of which is at TCAFCAA. 
The programmer need only modify the track identification and issue 
another DFHPC TYPE=PUT,TYPOPER=NEWREC macro instruction to add the 
record on another track. 

In the CICS/OS/VS system, the extended search option allows the 
record to be added to another track if no space is available on the 
specified track. Under these circumstances, the location at which 
the record was added is returned to the application program. 

2. The addition of keyed fixed— length records to DAM data sets 
requires that the data set first be formatted with dummy records or 
"slots" into which new records may be added. (The first byte of a 
dummy record is a key of hexadecimal FFs; in CICS/OS/VS, the first 
byte of data contains the record number.) A pre— formatted DAM data 
set cannot be added to by a COBOL batch program. 

3. For nonkeyed, fixed— length records, the exact physical block 
reference must be given in the record identification field. The 
data in the new records is written in the exact location specified, 
destroying the previous contents of that location. 

4. For keyed, fixed— length record additions, only the track 
information is used as a starting location for the search of a 
dummy key and record. When a dummy key and record are found, the 
new key and record replace it. The exact location at which the new 
record is located is returned to the application program in the 
block reference subfield of the record identification field. 

For example, suppose a user wishes to add a keyed, fixed— length 
record to a DAM data set. First, some algorithm determines that 
the search is to start at relative track 3. The record 
identification field of the new record might appear as follows: 

3 ALPHA 

T T R KEY 

When control is returned to the application program, the record 
identification field might reflect the fact that the record was 
added on relative track 4, record 6. 

4 6 ALPHA 
T T R KEY 
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5* When adding records of undefined length, the length of the physical 
record must be placed in two— byte binary format at TCAFCORL* When 
an undefined record is retrieved, the application program must 
determine its length. 

6. When making additions to a BDAH data set containing variable— length 
blocked or unblocked records, the application program must include 
a record descriptor field (RDF) which contains the length (LLpjrf) of 
the entire block to be written; Also, for each logical record 
within that block, an RDF must be included which contains the 
length of the logical record. Effectively, this allows the 
application to add a block containing multiple logical records as 
shown in Figure 3.2—9. 



I I 

FWA|PREFIX| 



I I 
96| 54 |< 




A 

I 

BLOCK 
RDF 



LOG 
REC 
RDF 



LOG 
REC 
RDF 



LOG 
REC 
RDF 



Figure 3i2— 9* Record Identification Field (Addition of More than 
One Record) 

If only a single logical record is to be added, the block RDF is 
still required, as shown in Figure 3a2— 10. 



I III 

FWA|PREFIX|108| 104 |<- 

I III 

i 



■100- 



->l 



A 

I 

BLOCK 



LOG 
REC 
RDF RDF 



Figure 3.2-10. 



Record Identification Field (Addition of Single 
Record) 



When updating records on a DAM dataset, the following restriction 
applies: 

If the file is blocked, and if two or more records are to be 
updated, a DFHFC TYPE=GET macro to retrieve a record must be 
followed by a DFHFC TYPE=PUT macro to write the updated record (or 
a DFHFC TYPE=RELEASE macro if the updated record is not required) 
before any further record in the same block is retrieved for 
update. Failure to do so will result either in one or more updates 
being lost or in a lockout. 
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Direct Retrieval (TYPE=GET) 



The format of the DFHFC macro instruction to retrieve single records 
directly from a data set is as follows: 




TYPE=GET 
,DATASET=symbolic name ] 
, RDIDADR=symbolic address] 
,SEGSET= {symbolic name | YES | ALL} ] 
,INDEX= {symbolic name|YES}] 
,TYPOPER=UPDATE] 

,RETMETH={RELREC|KEY} ] < 

,ARGTYP={KEY|RBA} ] <- 



,SRCHTYP= fFKE QlFKGE IGKEQIGKGE} ] 

, MOD E= {MOVE | LOCATE} ] < 

,DUPKEY=symbolic address] <— 

,NORESP=symbolic address] 
,ERROR=symbolic address] 
,DSIDER=symbolic address] 
, SEGIDER=symbolic address] 
,NOTFND=symbolic address] 
,INVREQ=symbolic address] 
, IOERROR=symbolic address] 
,DUPDS=symbolic address] 
,NOTOPEN=symbolic address] 
,ILLOGIC=symbolic address] <— 



—DAM 
-VSAM 
-VSAM 
-VSAM 



-VSAM & assembler 



-VSAM 



This macro instruction is used for direct read-only (inquiry) or 
update (DFHFC TYPE=GET, TYPOPER=UPDATE ) operations. The requested 
record is returned in: 

• a file input/output area (FIOA) for read-only operations with 
unsegmented, unblocked records from a DAM or ISAM data set or VSAM 
data set in move mode 

• a file work area (FWA) for update operations, read— only operations 
with segmented or blocked records, or for read-only operations with 
a blocked VSAM data set 

• in a VSAM buffer area for locate mode read-only operations on 
unsegmented records of a VSAM data set 

Before this macro is used, instructions must be provided that define 
symbolically the required FIOA, FWA and/or VSWA by: 

1. copying the appropriate storage definitions (DFHFIOA, DFHFWADS, 
and/or DFHVSWA) provided Jay CICS/VS 

2. providing storage definitions for the user's part of the FIOA, FWA, 
and/or the usar's record in the VSAM buffer 

N ote : Under CICS/OS/VS, if ISAM data is to be read into in an FIOA, a 
16-byte filler must be defined following the statement that copies 
DFHFIOA and preceding the user's data definition. 

CICS/VS performs the following services in response to a DFHFC 
TYPE=GET macro instruction: 

1. Acquires the main storage areas required to read a record 
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2. Reads the requested record 

3* Makes the requested record available to the application program. 

The record required in an input/output operation is identified in a 
record identification field. The format of this field, as required for 
the various access methods, is described under "Record Identification 
Field" , earlier in this chapter. 

When a DAM data set is referenced, the record identification field 
should contain a block reference. When an ISAM data set is referenced, 
the record identification field should contain a key. When a VSAM data 
set is referenced, the required record is accessed by either a relative 
byte address or a key. A search by key may be for a key equal to the 
search key, or for one equal to or greater than the search key, or for 
one equal to or less than the search key. A search may also be for a 
partial key (the first two bytes, or any number specified by the 
programmer), which may serve as a generic key. The generic or partial 
key search may, again, be either for an equal key or for an equal or 
greater key, or for an equal or less than key, but only the number of 
bytes specified will be compared. A protected, key— sequenced VSAM data 
set can be updated only by a full key equal search. 

In addition, CICS/VS can perform the following services, depending on 
the operands included in this macro instruction: 

• Retrieve a record indirectly 

• Segment a record for inquiry (read-only) and return the requested 
segments in a work area 

• Acguire a file work area when the record is to be updated, or when 
records are blocked or segmented 

• Unpack a segmented record into a work area of the same length as 
the requested record 

The length of an acquired FWA depends on whether or not the record is 
to be updated. If the record is to be updated, the FWA acquired will be 
sufficient to contain a record of the maximum length specified by the 
system programmer in the FCT; otherwise, the FWA will be sufficient to 
contain the requested record. 

When an unsegmented record of a VSAM data set is retrieved in 
response to a read— only request, move mode or locate mode processing can 
be specified. In move mode, the record is handled in the same way as 
any DAM or ISAM record. In locate mode, the record is made available to 
the application program in the VSAM buffer. The application programmer 
must have copied the symbolic storage definition for the VSWA (DFHVSWA) 
and must also provide a symbolic storage definition for the record that 
is retrieved. 

After requesting file services, the programmer must establish 
addressability for any required FIOA or FWA. The address of the area 
involved, provided by CICS/VS at TCAFCAA, must be placed in FIOABAR or 
FWACBAR. In locate mode, the address of the VSWA is in TCAFCAA and must 
be placed in VSWABAR. The address of the area that holds the requested 
record is at VSWAREA within the VSWA and must be moved to the base 
locator that has been established for the symbolic storage definition of 
the area. 

When retrieving variable— length records from a VSAM data set in move 
mode, the file control program creates a length field and places it 
preceding the record in the FWA* The format of this length field is 
LIW, where LL is a two— byte binary length (including the 4 bytes for 
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the length field itself) and J6)i is two bytes of binary zeros. In locate 
mode, the length is not included in the record itself but is placed at 
VSWALEN in the VSWA. 

When a VSAM record is retrieved for update, VSAM maintains exclusive 
control of the control interval containing that record. A task should 
not attempt to retrieve (for update) a second record from the same 
control interval as a record it is already holding for update, otherwise 
| a permanent wait will occur. The update should first be completed, by a 
| DFHPC TYPB=PUT macro, or if it cannot be completed, terminated by a 
DFHPC TYPE=RELEASE macro. 

A DFHPC TYPE=RELEASE macro instruction frees an FIOA or FWA acquired 
| in response to a request for file services, or a VSWA and VSAM string 
established for a VSAM read-only request using locate mode I/O* Any of 
these areas that are not freed by the application program are freed by 
CICS/VS at task termination* 



D irect Retrieval (Read— Only) 



The following examples show how to retrieve a single record directly 
from a master data set, assuming blocked records. 

For Assembler language ; 



COPY DFHTCADS 

KEYF DS CL8 

FWACBAR EQU 7 

COPY DFHFWADS 

RECORD DS 0CL3 50 



COPY TCA SYMBOLIC STRG DEFN 
RECORD IDENT FIELD IN TWA 
ASSIGN BASE REGISTER FOR FWA 
SYMBOLICALLY DEFINE FWA 
RECORD LAYOUT FOLLOWS CONTROL 
FIELD AND HAS SAME BASE REGISTER 



MVC KEYF,ACCTNO 
READREC DPHFC TYPE=GET, 

DATASET=MASTERA, 
RDIDADR=KEYF 

L FWACBAR, TCAFCAA 



MOVE RECORD IDENT TO KEY FIELD 
GET RECORD FROM MASTER DATA SET 



ESTABLISH ADDRESSABILITY FOR FHA 
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Fo r COBOL ; 

02 FHACBAE PIC S9 (8) COMP. 



NOTE DEFINE BASE REGISTER FOR FHA. 



01 DFHTCADS COPY DFHTCADS, 
02 KEYF PIC X(8) . 



NOTE COPY SYMBOLIC STRG DEFN FOR TCA, 
NOTE DEFINE KEY FIELD IN TWA. 



01 DFHFWADS COPY DFHFWADS. 
02 RECORD PIC X (350). 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA* 
NOTE DEFINE RECORD LAYOUT IN FWA. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR, 



NOTE ESTABLISH TCA ADDRESSABILITY. 



MOVE ACCTNO TO KEYF. 
READREC. 

DFHFC TYPE=GET, 

DATASET=MASTERA, 
RDIDADR=KEYF 
MOVE TCAFCAA TO FWACBAR. 



NOTE MOVE RECORD IDENT TO KEY* 
GET RECORD FROM MASTER DATA SET 

NOTE ESTABLISH FHA ADDRESSABILITY 



F or PL/I ; 

* INCLUDE DFHTCADS; 

02 KEYF CHAR (8) ; 
% INCLUDE DFHFWADS; 

02 RECORD CHAR (350) ; 



/*COPY SYMBOLIC STRG DEFN FOR TCA*/ 
/♦DEFINE KEY FIELD IN TWA*/ 
/*COPY SYMBOLIC STRG DEFN FOR FWA*/ 
/♦DEFINE RECORD LAYOUT IN FWA*/ 



KEYF=ACCTNO; 

READREC: 

DFHFC TYPE=GET, 

DATASET=MASTERA, 
RDIDADR=KEYF 

FWACBAR=TCAFCAA; 



/♦ASSIGN RECORD IDENT TO KEY FIELD*/ 
GET RECORD FROM MASTER DATA SET * 



/♦ESTABLISH ADDRESSABILITY FOR FWA*/ 
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Direct Retrie v al ( V SAM Locate M ode) 



The following examples show how to retrieve a single record directly 
from a VSAM data set using locate mode I/O. If the record is variable 
length, the LL## field will not be part of the record; The length of 
the record can be found in VSWALEN in the VSWA. 



For Assembler language 





COPY 


DFHTCADS 


KEYF 


DS 


CL8 


VSWABAR 


EQU 


7 


RECBAR 


EQU 


8 




COPY 


DFHVSWA 


RECDS 


DSECT 






USING 


*,RECBAR 


RECORD 


DS 


0CL350 



COPY TCA SYMBOLIC STORAGE DEFN 
DEFINE KEY FIELD IN TWA 
ASSIGN BASE REGISTER FOR VSWA 
ASSIGN BASE REGISTER FOR RECORD 
COPY VSWA SYMBOLIC DEFN 
DUMMY SECTION FOR RECORD 
MAKE RECORD ADDRESSABLE 
DEFINE RECORD LAYOUT 



MVC KEYF,ACCTNO 
READREC DFHFC TYPE=GET, 

DATA SET=MA STVS AM , 

RDIDADR=KBYF, 

MODE=LOCATE 

L VSWABAR, TCAFCAA 

L RECBAR ,VSWAREA 

L 3, VSWALEN 



MOVE RECORD ID TO KEY FIELD 
GET A RECORD FROM MASTER 

VSAM DATA SET USING 

LOCATE MODE 

ESTABLISH VSWA ADDRESSABILITY 
ESTABLISH RECORD ADDRESSABILITY 
LOAD RECORD LENGTH INTO WORK REG 



For COBOL ; 

02 VSWABAR PIC S9 (8) COMP. 
02 RECBAR PIC S9 (8) COMP* 



NOTE DEFINE BASE REGISTER FOR VSWA. 
NOTE DEFINE BASE REGISTER FOR RECORD. 



01 DFHTCADS COPY DFHTCADS. 
02 KEYF PIC X(8) . 
02 RECLEN PIC S9 (8) COMP. 



NOTE COPY SYMBOLIC STRG DEFN FOR TCA. 
NOTE DEFINE KEY FIELD IN TWA i 

NOTE DEFINE RECORD LENGTH WORK AREA* 



01 DFHVSWA COPY DFHVSWA. 
01 RECDS SYNCHRONIZED. 

02 RECORD PIC X (350) . 



NOTE COPY SYMBOLIC STRG DEFN FOR VSWA. 
NOTE DEFINE SYMBOLIC STRG DEFN FOR RECORD 
NOTE DEFINE RECORD LAYOUT. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR 



NOTE ESTABLISH TCA ADDRESSABILITY. 



MOVE ACCTNO TO KEYF. 
READREC* 

DFHFC TYPE=GET, 

DATASET=MASTVSAM, 
RDIDADR=KEYF, 
MODE=LOCATE 
MOVE TCAFCAA TO VSWABAR. 
MOVE VSWAREA TO RECBAR. 
MOVE VSWALEN TO RECLEN* 



NOTE MOVE RECORD ID TO KEY FIELD* 

GET A RECORD FROM MASTER * 

VSAM DATA SET USING * 

LOCATE MODE * 

NOTE ESTABLISH VSWA ADDRESSABILITY. 
NOTE ESTABLISH RECORD ADDRESSABILITY. 
NOTE MOVE RECORD LENGTH TO WORK AREA. 
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For PL/I ; 

^INCLUDE DFHTCADS; 

02 KEYF CHAR (8) , 

02 EECLEN FIXED BINARY (31); 
%INCLUDE DFHVSWA; 
DCL 01 RECDS BASED (RECBAR) , 

02 RECORD CHAR (350); 



/♦COPY SYMBOLIC STRG DEFN FOR TCA*/ 
/♦DEFINE KEY FIELD IN TWA*/ 
/♦DEFINE RECORD LENGTH WORK AREA*/ 
/♦COPY SYMBOLIC STRG DEFN FOR VSWA*/ 
/♦DEFINE SYMB STRG DEFN FOR RECORD*/ 
/♦DEFINE RECORD LAYOUT*/ 



KEYF=ACCTNO; 

READREC: 

DFHFC TYPE=GET, 

DATASET=MASTVASM, 

RDIDADR=KEYF, 

MODE=LOCATE 

VSWABAR=TCAFCAA; 

RECBAR=VSWAREA; 

RECLEN=VSWALEN; 



/*MOVE RECORD ID TO KEY FIELD*/ 

GET A RECORD FROM MASTER 
VSAM DATA SET USING 
LOCATE MODE 

/♦ESTAB ADDRESSABILITY FOR VSWAV 
/♦ESTAB ADDRESSABILITY FOR RECORD*/ 
/*MOVE RECORD LENGTH TO WORK AREA*/ 



Direct Retrieval (for update) 



The following examples show how to retrieve a single record directly 
from a master data set for update. 

For Assembler language ; 



COPY DFHTCADS 

KEYF DS CL8 

FWACBAR BQU 7 

COPY DFHFWADS 

RECORD DS 0CL350 



COPY TCA SYMBOLIC STRG DEFN 
DEFINE KEY FIELD IN TWA 
ASSIGN BASE REGISTER FOR FWA 
SYMBOLICALLY DEFINE FWA 
RECORD LAYOUT FOLLOWS CONTROL 
FIELD AND HAS SAME BASE REGISTER 



i 

MVC KEYF,ACCTNO 
READREC DFHFC TYPE=GET, 

DATASET=MASTERA, 

RDIDADR=KEYF, 

TYPOPER=UPDATE 

L FWACBAR, TCAFCAA 



MOVE RECORD IDENT TO KEY FIELD 
GET RECORD FROM MASTER DATA SET 
FOR UPDATE 



ESTABLISH ADDRESSABILITY FOR FWA 
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For COBOL : 

02 FWACBAR PIC S9 (8) COMP 



NOTE DEFINE BASE REGISTER FOR FWA 



01 DFHTCADS COPY DFHTCADS, 
02 KEYF PIC X (8) . 



NOTE COPY SYMBOLIC STRG DEFN FOR TCA* 
NOTE DEFINE KEY FIELD IN TWA. 



01 DFHFWADS COPY DFHFWADS, 
02 RECORD PIC X (350) . 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA. 
NOTE DEFINE RECORD LAYOUT IN FWA. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR. 



NOTE ESTABLISH TCA ADDRESSABILITY 



MOVE ACCTNO TO KEYF. 
READREC* 

DFHFC TYPE=GET / 

DATASET=MASTERA, 
RDIDADR=KEYF, 
TYPOPER=UPDATE 
MOVE TCAFCAA TO FWACBAR . 



NOTE MOVE RECORD IDENT TO KEY* 

GET RECORD FROM MASTER DATA SET * 

* 

NOTE ESTABLISH FHA ADDRESSABILITY* 



F or PL/I : 

96INCLUDE DFHTCADS; 

02 KEYF CHAR (8) ; 
%INCLUDE DFHFWADS; 

02 RECORD CHAR (350) ; 



/♦COPY SYMBOLIC STRG DEFN FOR TCA*/ 
/♦DEFINE KEY FIELD IN TWA*/ 
/♦COPY SYMBOLIC STRG DEFN FOR FWA*/ 
/♦DEFINE RECORD LAYOUT IN FWA*/ 



KEYF=ACCTNO; 

READREC: 

DFHFC TYPE=GET, 

DATASET=MASTERA, 
RDIDADR=KEYF, 
TYPOPER= UPDATE 

FWACBAR=TCAFCAA; 



/♦ASSIGN RECORD IDENT TO KEY FIELDV 
GET RECORD FROM MASTER DATA SET * 

/*ESTABLISH ADDRESSABILITY FOR FWA*/ 
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Indirect Retrieval (Indirect Access) 



The following examples show how to retrieve a single record for update 
when its key is unknown* A cross—index data set containing the master 
key is available, making it possible to access the record indirectly. 
(See "Indirect Accessing", earlier in this chapter) . 



For Assembler language : 

COPY DFHTCADS 

KEYF DS CL25 

FWACBAR EQU 7 

COPY DFHFWADS 

RECORD DS 0CL3 50 



COPY TCA SYMBOLIC STRG DEFN 
DEFINE KEY FIELD IN TWA 
ASSIGN BASE REGISTER FOR FWA 
SYMBOLICALLY DEFINE FWA 
RECORD LAYOUT FOLLOWS CONTROL 
FIELD AND HAS SAME BASE REGISTER 



MVC KEYF,INDEXA 
READING DFHFC TYPE=GET, 

DATASET=MASTERA, 
RDIDADR=KEYF, 
TYPOPER=UPDATE, 
INDEX=INDIRECT 

L FWACBAR, TCAFCAA 



MOVE INDEX IDENT TO KEY FIELD 
GET RECORD FROM MASTER DATA SET 
BY FIRST ACCESSING A CROSS-INDEX 
DATA SET NAMED INDIRECT 



ESTABLISH ADDRESSABILITY FOR FWA 



For COBOL : 

02 FWACBAR PIC S9 (8) COMP* 



NOTE DEFINE BASE REGISTER. 



01 DFHTCADS COPY DFHTCADS. 
02 KEYF PIC X (25) * 



NOTE COPY SYMBOLIC STRG DEFN FOR TCA. 
NOTE DEFINE KEY FIELD IN TWA. 



01 DFHFWADS COPY DFHFWADS. 
02 RECORD PIC X (350) . 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA* 
NOTE DEFINE RECORD LAYOUT IN FWA. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR. 



NOTE ESTABLISH TCA ADDRESSABILITY. 



MOVE PARTNAME TO KEYF. 
READREC. 

DFHFC TYPE=GET, 

DATASET=MASTERA, 
RDIDADR=KEYF, 
TYPOPER=UPDATE, 
INDEX=INDEXAB 
MOVE TCAFCAA TO FWACBAR. 



NOTE MOVE INDEX IDENT TO KEY* 

GET RECORD FROM MASTER DATA SET 
BY FIRST ACCESSING A CROSS-INDEX 
DATA SET NAMED INDEXAB 



NOTE ESTABLISH FWA ADDRESSABILITY 
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^INCLUDE DFHTCADS; 

02 KEYF CHAR (25) ; 
^INCLUDE DFHFWADS; 

02 RECORD CHAR (350) ; 



/♦COPY SYMBOLIC STRG DEFN FOR TCA*/ 
/♦DEFINE KEY FIELD IN TWAV 
/♦COPY SYMBOLIC STRG DEFN FOR FWAV 
/♦DEFINE RECORD LAYOUT IN FWAV 



KEYF=PARTNAME? 

READREC: 

DFHFC TYPE=GET, 

DATASET=MASTERA, 
RDIDADR=KEYF, 
TYPOPER=UPDATE, 
INDEX=INDEXAB 

FWACBAR=TCAFCAA; 



/♦ASSIGN INDEX IDENT TO KEY FIELDV 

GET RECORD FROM MASTER DATA SET 
BY FIRST ACCESSING A CROSS-INDEX 
DATA SET NAMED INDEXAB 



/♦ESTABLISH ADDRESSABILITY FOR FWAV 
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Direct Update or Addition (TYPE=PUT). 



The format of the DFHFC macro instruction to update or add single 
records to a data set is as follows: 



DPHPC 



TYPE=PUT 
,RDIDADR=symbolic address] 
,SEGSET=YES] 

,TYPOPER= fNEWREC I UPDATE I DBLETE1 ] (See note) 
,ARGTYP=fKEY|RBA> 1 < 



,NORESP=symbolic address] 
,ERROR=symbolic address] 
,DUPREC=symbolic address] 
r INVREQ=symbolic address] 
f IOERROR=symbolic address] 
,NOSPACE=symbolic address] 
,NOTOPEN=symbolic address] 
, ILLOGIC=symbolic address] 



-VSAM 



-VSAM 



Note ; DELETE can be used only with a VSAM KSDS or RRDS 



This macro instruction is used to: 

• update an existing record that has been retrieved through the DFHFC 
TYPE=GET,TYPOPER=UPDATE macro instruction 

• add a new record to an existing data set 

• update an existing record in a nonkeyed DAM data set without first 
reading the record for update 

A DFHFC TYPE=PUT macro instruction must never be issued without first 
issuing a DFHFC TYPE=GET,TYPOPER=UPDATE or DFHFC TYPE=GETAREA macro 
instruction, because the results of such action are unpredictable. 

When a VSAM key— sequenced or relative— record data set is being 
processed, a DFHFC TYPE=PUT,TYPOPER=DELETE macro instruction can be used 
to delete a record previously retrieved by a DFHFC 
TYPE=GET,TYPOPER=UPDATE macro instruction ; 

A file work area (FWA) is used to contain the record or segments to 
be written or updated. The first 16 bytes of the FWA form the CICS/VS 
system section, which is followed by the actual record or segments to be 
written to a data set. 

CICS/VS performs the following services in response to a DFHFC 
TYPE=PUT macro instruction: 

• Writes updated or new records in user— defined data sets 

• Acquires or locates the main storage and control blocks required to 
write the record 

• Releases all data set storage associated with the request to write 

• Packs a segmented record, depending on the data set organization 
and the operands included in this macro instruction 
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Before file services can be requested by means of the DFHFC TYPE=POT 
macro instruction, the application program must include instructions 
that do the following: 

1. Symbolically define the FWA by (1) copying the appropriate system 
section storage definition (DFHFWADS) , and (2) providing a storage 
definition for the user's section of the FWA. 

2* Establish addressability for the new FWA by specifying a symbolic 
base address for the FWAi 

3a Place the address of the FWA in TCAFCAA* This address was made 

available to the application program by CICS/VS in response to the 
DFHFC TYPE=GET or DFHFC TYPE=GETAREA request by which the FWA was 
acquired. It must have been stored by the application program at 
that time, and should be moved to TCAFCAA immediately preceding the 
DFHFC TYPE=PUT request, with no intervening requests that could 
cause the contents of TCAFCAA to be altered. 

If the records being written to a data set are undefined, the length 
of the record being written must be placed in TCAFCURL. 

For records written to a variable— length VSAM data set, the length of 
the record should be placed in an LL#Jzf field in the beginning of the 
record. The field is four bytes long, the first two bytes containing 
the length in binary (including the 4— fiytes for the length field) and 
the last two bytes set to binary zeros. This field is used by CICS/VS 
to determine the length of the record and is not written to the data 
set. 

| VSAM does not allow an update operation on a control interval from 
which a record has already been retrieved for update. If a task 

| attempts to perform an update operation on such a control interval 
before a previous record already held by the same task is updated by a 
DFHFC TYPE=PUT, or before the update is terminated by a DFHFC 

| TYPE=RELEASE, the program will go into a permanent wait. 

The programmer who is adding records to a DAM data set should also 
refer to "DAM Data Sets" earlier in this chapter. 

The following examples show how to retrieve a record at random, 
update it, and return it to the data set. 



F or Assembler languag e; 





COPY 


DFHTCADS 


KEYF 


DS 


CL8 


FWACBAR 


EQU 


7 




COPY 


DFHFWADS 


RECORD 


DS 


0CL350 



COPY TCA SYMBOLIC STRG DEFN 
DEFINE KEY FIELD IN TWA 
ASSIGN BASE REGISTER FOR FWA 
SYMBOLICALLY DEFINE FWA 
RECORD LAYOUT FOLLOWS CONTROL 
FIELD AND HAS SAME BASE REGISTER 



READUPD DFHFC TYPE=GET, 

DATASET=MASTERB, 
RDIDADR=KBYF, 
TYPOPER=UPDATE 
L FWACBAR, TCAFCAA 

* (update record) 

ST FWACBAR, TCAFCAA 
WRITEUP DFHFC TYPE=PDT, 

RDIDADR=KEYF 



READ RECORD FOR UPDATE 



ESTABLISH ADDRESSABILITY FOR FWA 



PLACE FWA ADDRESS IN TCA 
WRITE THE UPDATED RECORD 
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For COBOL : 

02 FWACBAR PIC S9 (8) COMP, 



NOTE DEFINE BASE REGISTER FOR FWA. 



01 DFHTCADS COPY DFHTCADS 
02 KEYF PIC X(8) . 



NOTE COPY SYMBOLIC STRG DEFN FOR TCA, 
NOTE DEFINE KEY FIELD IN TWA. 



01 DFHFWADS COPY DFHFWADS 
02 RECORD PIC X(350) . 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA 
NOTE DEFINE RECORD LAYOUT IN FWA. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR 



NOTE ESTABLISH TCA ADDRESSABILITY. 



READUPD. 

DFHFC TYPE=GET, 

DATASET=MASTERB, 
RDIDADR=KEYF, 
TYPOPER=UPDATE 
MOVE TCAFCAA TO FWACBAR. 

. (update record) 

MOVE FWACBAR TO TCAFCAA. 
WRITEUP. 

DFHFC TYPE=PUT, 

RDIDADR=KEYF 



READ RECORD FOR UPDATE * 

* 
* 



NOTE ESTABLISH FWA ADDRESSABILITY. 

NOTE MOVE ADDRESS OF FWA TO TCA. 
WRITE THE UPDATED RECORD * 



F or PL/I ; 

^INCLUDE DFHTCADS; 

02 KEYF CHAR (8) ; 
%INCLUDE DFHFWADS; 

02 RECORD CHAR (350); 



/♦COPY SYMBOLIC STRG DEFN FOR TCA*/ 
/♦DEFINE KEY FIELD IN TWA*/ 
/*COPY SYMBOLIC STRG DEFN FOR FWA*/ 
/♦DEFINE RECORD LAYOUT IN FWA*/ 



READUPD: 

DFHFC TYPE=GET, 

DATASET=MASTERB, 

RDIDADR=KEYF, 

TYPOPER=UPDATE 

FWACBAR=TCAFCAA; 

. (update record) 

• 

TCAFCAA=FWACBAR; 
WRITEUP: 

DFHFC TYPE=PUT, 

RDIDADR=KEYF 



READ RECORD FOR UPDATE * 

* 



/♦ESTABLISH ADDRESSABILITY FOR FWA*/ 

/*PLACE ADDR OF WORK AREA IN TCA*/ 
WRITE THE UPDATED RECORD * 
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Direct Deletion, VSAM Only (TYPE=DELETE) 

The format of the DFHFC macro instruction to delete a record or group of 
| records directly from a VSAM KSDS or BEDS is as follows: 




TYPE=DELETE 

[ ,DATASET=symbolic name] 

[ ,RDIDADR=symbolic address] 

[ ,ARGTYP=KEY] 

[ ,SRCHTYP=f FKEQ |GKEQl ] 

[ ,NORESP=symbolic address] 

[ ,ERROR=symbolic address] 

[ ,DSIDER=symbolic address] 

[ ,NOTFND=symbolic address] 

[ ,INVREQ=symbolic address] 

[ , IOERROR=symbolic address] 

[ , NOTOPEN=symbolic address] 

[ ,ILLOGIC=symbolic address] 



DFHFC TYPE=DELETE can be used to perform the following functions on 
VSAM key— seguenced and relative— record data sets only.: 

• Delete a single record* 

© Delete a group of records that share the same partial key; that is 
where the first part of the keys is the same. This is called 
generic delete. 

To delete a single record, the key must be placed in an area pointed 
to by the RDIDADR operand. 

To delete a group of records with the same partial key, that is where 
the first part of the keys is the same, the partial key must be placed 
in an area pointed to by the RDIDADR operand. The binary length of the 
key must be placed in the first byte of the area pointed to by the 
RDIDADR operandi SRCHTYP=GKEQ must be specified. 

Group deletes must not be attempted on data sets for which automatic 
logging has been specified, (DFHFCT TYPE=DATASET,LOG=YES) . An attempt 
to do so will result in an invalid reguest condition. 

Neither an FIOA nor an FWA is required for a delete operation. 

Note that a DELETE operation is an update operation, and therefore 
the control interval concerned is held under exclusive control. 
Exclusive control is released either by successful completion of the 
DELETE operation, or failing this, by issuing a DFHFC TYPE=RBLEASE 
macro* 
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Obtain a File Work Area (TYPE = GET ARE A) 



The format of the DFHFC macro instruction to obtain a file work area 
(FWA) for the application program is as follows: 




TYPE=GETAREA 
, DATASET=symbolic name] 
,INITIMG= {value | YES) ] 
,TYPOPER=MASSINSERT] <- 
,ARGTYP={KEY|RBA) ] < 



-VSAM 
-VSAM 



,NORESP=symbolic address] 
,ERROR=symbolic address] 
,DSIDER=symbolic address] 
,INVREQ=symbolic address] 
,NOTOPEN=symbolic address] 



The new main storage area is a file work area (FWft) and can be 
obtained only by this macro a (A storage control DFHSC TYPE=GETMAIN 
request cannot be used for file operations* ) 

CICS/VS performs the following services in response to a DFHFC 
TYPE=GETAREA macro instruction: 

1. Acquires main storage (an FWA) for the creation of a new record 

2* Includes and initializes the FWA control fields (a 16-byte prefix 
to the FWA) required by file control 

If several new records whose keys are in ascending sequence are to be 
added to a VSAM data set, the TYPOPER=MASSINSERT operand should be used, 
in which case, the FWA is retained and made available to the application 
program after each DFHFC TYPB=PUT macro instruction that adds a record 
to the data set. A mass insert operation is terminated by a DFHFC 
TYPE=RELEASE macro instruction. A lockout condition will occur if more 
than one transaction is simultaneously attempting to perform a mass 
| insert to the same control interval of a protected data set. A lockout 
| will occur also if a transaction uses keys that are not in ascending 
| sequence. 

In a DFHFC TYPE=GETAREA macro, the ARGTYP operand is only applicable 
when TYPOPER=MASSINSERT has been specified. 

When the DFHFC TYPE=GETAREA macro instruction is used, the 
application program must include instructions that do the following: 

o Symbolically define the FWA by (1) copying the appropriate CICS/VS 
system section storage definition (DFHFWADS) , and (2) providing a 
storage definition for the user's section of the FWA. 

o Establish addressability for the new FWA by specifying a symbolic 
base address for the FWA* (The address of the area involved, 
returned by CICS/VS at TCAFCAA, must be placed in FWACBAR .) 

The following examples show how to obtain an FWA, build a new record 
in the FWA, and write that record to a data set. 
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For Assembler language : 

COPY DFHTCADS 

KEYF DS CL8 

FWACBAR EQO 7 

COPY DFHFWADS 

RECORD DS 0CL350 



COPY TCA SYMBOLIC STRG DEFN 
DEFINE KEY FIELD IN TWA 
ASSIGN BASE REGISTER FOR FWA 
SYMBOLICALLY DEFINE FWA 
RECORD LAYOUT FOLLOWS CONTROL 
FIELD AND HAS SAME BASE REGISTER 



NEWREC DFHFC TYPE=GETAREA, 

DATASET=MASTERC 
L FWACBAR, TCAFCAA 

. (build new record) 

ST FWACBAR, TCAFCAA 
WRITNEW DFHFC TYPE=PUT, 

TYPOPER=NEWREC, 
RDIDADR=KEYF 



OBTAIN A FWA TO CREATE A NEW 

RECORD FOR A DATA SET 

ESTABLISH ADDRESSABILITY FOR FWA 



PLACE ADDR OF NEW RECORD IN TCA 
WRITE THE NEW RECORD 



For COBOL : 

02 FWACBAR PIC S9 (8) COMP. 



NOTE DEFINE BASE REGISTER FOR FWA 



01 DFHTCADS COPY DFHTCADS. 
02 KEYF PIC X (8). 



NOTE COPY SYMBOLIC STRG DEFN FOR TCA, 
NOTE DEFINE KEY FIELD IN TWA. 



01 DFHFWADS COPY DFHFWADS. 
02 RECORD PIC X (350) . 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA, 
NOTE DEFINE RECORD LAYOUT IN FWA. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR. 



NOTE ESTABLISH TCA ADDRESSABILITY. 



NEWREC. 

DFHFC TYPE=GETAREA, 

DATASET=MASTERC 
MOVE TCAFCAA TO FWACBAR. 
* 
• (build new record) 

• 

MOVE FWACBAR TO TCAFCAA. 
WRITNEW. 

DFHFC TYPE=PUT, 

TYPOPER=NEWREC, 
RDIDADR=KEYF 



OBTAIN A FWA TO CREATE A NEW 

RECORD FOR A DATA SET 

NOTE ESTABLISH FWA ADDRESSABILITY. 



NOTE ADDRESS OF NEW RECORD TO TCA. 
WRITE THE NEW RECORD 
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For PL/I : 

% INCLUDE DFHTCADS; 

02 KETF CHAR (8) ; 
^INCLUDE DFHFWADS; 

02 RECORD CHAR (350) ; 



/♦COPY SYMBOLIC STRG DEFN FOR TCA*/ 
/♦DEFINE KEY FIELD IN TWA*/ 
/♦COPY SYMBOLIC STRG DEFN FOR FWA*/ 
/♦DEFINE RECORD LAYOUT IN FWAV 



NEWRECl 

DFHFC TYPE=GETAREA, 

DATASET=MASTERC 
FWACBAR=TCAFCAA; 

(build new record) 

TCAFCAA=FWACBAR; 
WRITNEW: 

DFHFC TYPE=PUT, 

TYPOPER=NEWREC r 
RDIDADR=KEYF 



OBTAIN A FWA TO CREATE A NEW 

RECORD FOR A DATA SET 

/♦ESTABLISH ADDRESSABILITY FOR FWAV 



/♦PLACE ADDR OF NEW RECORD IN TCAV 



WRITE THE NEW RECORD 
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Release Storage/Exclusive Control (TYPE = RELEASE) 

The format of the DFHFC macro instruction to release a record from 
exclusive control, if applicable, and to release storage areas acquired 
for a record is as follows: 



TYPE=RELEASE 

[ ,NORESP=symbolic address] 

[ ,ERROR=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,IOERROR=symbolic address] 

[ ,ILLOGIC=symbolic address] < VSAM 



If the storage area to be released contains a record that has been 
read for update (by means of a DFHFC TYPE=GET,TYPOPER=UPDATE macro), and 
the update is no longer required, this macro will release the record 
from exclusive control as well as free the storage areas associated with 
it. 

Before the DFHFC TYPE=RELEASE macro instruction is executed, the 
address of the FWA, FIOA, or VSWA to be released must be moved to 
TCAFCAA. Any associated areas are also released* 

A mass insert operation on a VSAM data set (initiated by the 
TYPOPER=MASSINSERT operand, followed by DFHFC TYPE=PUT,TYPOPER=NEWREC 
macro instructions) is terminated by a DFHFC TYPE=RELEASE macro 
instruction* 

A DFHFC TYPE=RELEASE macro instruction should also be used to release 
the VSWA established by CICS/VS in response to a read— only request for a 
VSAM data set record retrieved in locate mode. Failure to release the 
VSWA may cause significant performance degradation or task suspension if 
subsequent accesses are made to the file. 

The DFHFC TYPE=RELEASE macro instruction should not be specified if 
the DFHFC TYPE=PUT,TYPOPER=UPDATE macro instruction is used to perform a 
successful write of an updated record back to a data set. CICS/VS 
automatically releases all storage associated with the write operation. 
However, if an error condition occurs, preventing successful completion 
of the write, a DFHFC TYPE=RELEASE macro instruction should be issued to 
release the storage. 

DFHFC TYPE=RELEASE must be issued whenever a DUPREC, ILLOGIC, 
IOERROR, or NOTFND condition occurs. For further details of these 
conditions, see "Operands of DFHFC Macro" at the end of this chapter. 

CICS/VS performs the following services in response to a DFHFC 
TYPE=RELEASE macro instruction: 

• Releases an FWA, FIOA, and/or VSWA 

• Releases a VSAM string, if a VSWA is released 

• Releases exclusive control of a record retrieved for update (if 
applicable) 

Note, though, that for a file with auto— logging specified (by the 
system programmer) , the resource remains under the task control enqueue 
until either a sync point is issued or end of task is reached. 
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I There is a limit to the number of VSAM strings that may be in use at 
| any one time, determined by the STRNO operand of the DFHFCT TYPE=DATASET 
I system macro instruction* If strings are not released when no longer 
| required, tasks may have to wait unnecessarily owing to the strings all 
| being in use. 

| Any FWAs, FIOAs, VSWAs, and VSAM strings acquired during execution of 
a task are automatically released at termination of the task, if not 
released earlier in response to to a DFHFC TYPE=RELEASE macro 
instruction. 

The following examples show how to request the release of an FWA. 



For Assembler language ; 



FWACBAR EQO 

COPY 
RECORD DS 



DFHFWADS 
0CL3 50 



ASSIGN BASE REGISTER FOR FWA 
SYMBOLICALLY DEFINE FWA 
RECORD LAYOUT FOLLOWS CONTROL 
FIELD AND HAS SAME BASE REGISTER 



ST FWACBAR,TCAFCAA 
RLSEREC DFHFC TYPE=RELEASE 



ADDRESS OF FWA TO BE RELEASED 
IN TCA AND ISSUE RELEASE REQUEST 



For COBOL ; 

02 FWACBAR PIC S9 (8) COMP. 



NOTE DEFINE BASE REGISTER FOR FWA. 



| 01 DFHFWADS COPY DFHFWADS. 
02 RECORD PIC X (350) . 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA* 
NOTE DEFINE RECORD LAYOUT IN FWA. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR. 



NOTE ESTABLISH TCA ADDRESSABILITY 



MOVE FWACBAR TO TCAFCAA. 
RLSEREC. 

DFHFC TYPE=RELEASE 



NOTE ADDR OF FWA TO BE RELEASED. 
ISSUE RELEASE REQUEST 



For PL/I ; 
^INCLUDE DFHTCADS; 



/*COPY SYMBOLIC STRG DEFN FOR TCA*/ 



^INCLUDE DFHFWADS; 

02 RECORD CHAR (350); 



/*COPY SYMBOLIC STRG DEFN FOR FWA*/ 
/♦DEFINE RECORD LAYOUT IN FWA*/ 



TCAFCAA=FWACBAR; 
RLSEREC: 

DFHFC TYPE=RELEASE 



/♦ADDRESS OF FWA TO BB RELEASED*/ 
ISSUE RELEASE REQUEST 
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Initiate Browse (TYPE=SETL) 



The format of the DFHPC macro instruction to initiate a browse operation 
on a data set is as follows: 




TYPE=SETL 
,DATASET=symbolic name] 
,RDIDADR=symbolic address] 
,SEGSET= {symbolic name | YES | ALL) ] 

,RETMETH={RELREC|KEY) ] < 

,ARGTYP={KEY|RBA) ] < 

,SRCHTYP={FKEQ|FKGE|GKEQ|GKGE) ] 

, MODE= {MOVE | LOCATE) ] < 

,NORESP=symbolic address] 
,ERROR=symbolic address] 
, DSIDER=symbolic address] 
,SEGIDER=symbolic address] 
,NOTFND=symbolic address] 
, INVREQ=symbolic address] 
,IOERROR=symbolic address] 
, NOTOPEN=symbolic address] 
,ILLOGIC=symbolic address] < — 



—DAM 
-VSAM 
-VSAM 
-VSAM 



-VSAM 



This macro instruction is used to establish the position within the 
data set where the browse operation is to begin. It must be issued 
before any DPHFC TYPE=GETNEXT macro instruction; however, no data is 
available until a DFHFC TYPE=GETNEXT is used. 

The starting point within a data set for a browse operation is 
identified by a record identification field established for the data 
set. (See "Record Identification Field", earlier in this chapter.) 

For an ISAM data set, the browse operation begins at the first record 
with a key equal to or greater than the key provided in the record 
identification field. This key may be either a specific (complete) key 
or a generic (partial) key. For example, a complete key of D6 42BR17 
causes sequential processing to begin at the first record with a key 
equal to or greater than that key* 

A generic key is one in which the application programmer supplies 
only the significant characters of a desired group of keys, padding the 
remainder of the key field with blanks or binary zeros* Considering a 
data set whose records had eight byte key fields, then a generic key of 
9 6H2^)fff would cause sequential processing to begin at the first record 
with a key whose first four characters were equal to or greater than 
9642. A key field of all binary zeros causes sequential processing to 
begin at the first record of the data set. 

For a DAM data set, the record identification field must contain a 
block reference (for example, TTR or MBBCCHHR) which conforms to the 
addressing method defined for that data set. Processing begins with the 
specified block and continues with each subsequent block until the 
browse operation is terminated. If the data set contains blocked 
records, processing begins at the first record of the first block and 
continues with each subsequent record. 

For a VSAM data set, the contents of the record identification field 
may be either a key, a relative byte address, or a relative record 
number. If the field contains a relative byte address, the browse 
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operation begins at the specified address. If the field contains a key, 
it may be either specific or generic. If the key is generic, the length 
of the partial key is specified in the first byte of the record 
identification field. In either case, the application program can 
specify that the browse operation is to begin at the first record having 
a key (1) egual to the key in the record identification field (for 
generic, compared on only the number of bytes specified) , or (2) equal 
to or greater than the key in the record identification field (again, 
for generic, compared on only the bytes specified). 

When the DFHPC TYPE=SETL macro instruction is used, the application 
programmer must provide instructions that do the following: 

• Symbolically define the FWA by (1) copying the appropriate CICS/VS 
system section storage definition (DFHFWADS) , and (2) providing his 
own storage definition for the user^s section of the FWA. 

• Establish addressability for the FWA by specifying a symbolic base 
address for the FWA, typically following the DFHFC macro 
instruction. (The address of the FWA, provided by CICS/VS at 
TCAFCAA, must be placed at FWACBAR upon normal return from 
execution of the SETL macro instruction*) 
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In most cases, records retrieved during a browse operation are 
returned to the application program in a file work area (FWA). However, 
in locate mode the addresses of the record are passed in the VSWA. The 
FWA allocated by CICS/VS following a SETL request is unique for the 
duration of that particular browse operation. If the application 
program issues another SETL request, for the same or another data set, a 
different FWA is created by CICS/VS* Thus it is possible for a single 
application program to concurrently browse the same data set at several 
different locations. 

During a browse operation on a segmented data set, the original FWA 
(that is, the one allocated by CICS/VS in response to the SETL request) 
may be replaced with a different FWA if a segment set specified in a 
GETNEXT request requires a larger FWA than the segment set specified in 
the SETL request. In this situation, the application programmer should 
not assume that the same FWA is used for all GETNEXT requests. The 
address of the utilized FWA is available at TCAFCAA upon return from a 
GETNEXT request. 

CICS/VS performs the following services in response to a DFHFC 
TYPE=SETL macro instruction: 

1 . Acquires the main storage I/O areas and work areas to be associated 
with this browse operation 

2. Preserves the segment set name (if any) as the default segment set 
name to be used if none is specified in subsequent GETNEXT requests 

3. Returns the address of the allocated FWA in TCAFCAA for other than 
locate-mode nonsegmented VSAM data set processing; returns the 
address of the allocated VSWA that will contain the VSAM buffer- 
area address of each retrieved record for locate— mode nonsegmented 
VSAM data set processing 

The information supplied by the user in the record identification 
field is preserved by CICS/VS for use when GETNEXT requests are issued. 
Since CICS/VS places into this field the identification of each record 
retrieved in response to a subsequent GETNEXT request, the field should 
not be released by the application program. 

The information placed into the record identification field by 
CICS/VS is always in a form which completely identifies the record* For 
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example, assume a browse operation is to start with the first record of 
a blocked, keyed DAM data set. Before issuing the DPHFC TYPE=SETL macro 
instruction, the application programmer should place the TTR (assuming 
that is the addressing method) of the first block into the record 
identification field* After executing each DPHFC TYPE=GETNEXT macro 
instruction, CICS/VS places the complete record identification into the 
record identification field* After the first GETNEXT, the record 
identification field might contain 

X«0000010504» 

where 000001 represents the TTR value, 05 represents the block key, and 
04 represents the record key. 

As another example, if the application program is browsing a blocked, 
nonkeyed DAM data set and the second record from the second physical 
block on the third relative track is read in response to a GETNEXT 
reguest, the record identification field contains 

X»00020201» 

upon return to the application program, where 0002 represents the track, 
02 represents the block, and 01 represents the record within the block. 

The following examples show how to initiate a browse operation. 



For Assembler language : 



COPY DFHTCADS 

KEYF DS CL8 

FWACBAR EQO 7 

COPY DFHFWADS 

RECORD DS 0CL350 



COPY TCA SYMBOLIC STORAGE DEFN 

ASSIGN BASE REGISTER FOR FWA 
DEFINE SYSTEM SECTION OF FWA 
RECORD LAYOUT 



CSECT 



MVC KEYF (5) ,=C» JONES' 
XC KEYF+5 (3),KEYF+5 

START DFHFC TYPE=SETL, 

DATASET=MASTER, 
RDIDADR=KEYF, 
NOTOPEN=ERROR 
L FWACBAR, TCAFCAA 



INITIALIZE KEY FIELD 
INITIATE BROWSE 



GO TO ERROR LABEL IF ERROR 
ESTABLISH ADDRESSABILITY FOR FWA 



ERROR DS 



OH 



ENTRY TO ERROR ROUTINE 
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For COBOL ; 

02 FWACBAR PIC S9(8) COMP* 



01 DFHTCADS COPY DFHTCADS. 

02 KEYF PIC X (8). 
01 DFHFWADS COPY DFHFWADS* 

02 RECORD PIC X (350) . 



NOTE DEFINE BASE REGISTER FOR FWA. 

NOTE COPY SYMBOLIC STRG DEFN FOR TCA. 
NOTE DEFINE KEY FIELD IN TWA. 
NOTE COPY SYMBOLIC STRG DEFN FOR FWA. 
NOTE DEFINE RECORD LAYOUT IN FWA. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR. 



NOTE ESTABLISH TCA ADDRESSABILITY. 



MOVE 'JONES* TO KEYF. 
START. 

DFHFC TYPE=SETL, 

DA TASET=M ASTER, 
RDIDADR=KEYF, 
NOTOPEN=ERROR 
MOVE TCAFCAA TO FWACBAR* 



INITIATE BROWSE 



GO TO ERROR LABEL IF ERROR 



ERROR. 



For PL/I ; 

^INCLUDE DFHTCADS? 
02 KEYF CHAR (8) ; 



/*COPY SYMBOLIC STRG DEFN FOR TCA*/ 



%INCLUDE DFHFWADS; 

02 RECORD CHAR (350) ; 



/*COPY SYMBOLIC STRG DEFN FOR FWA*/ 
/♦DEFINE RECORD LAYOUT IN FWA*/ 



KEYF^JONES 1 ; 

START; 

DFHFC TYPE=SETL, 

DATASET=MASTER, 

RDIDADR=KEYF, 

NOTOPEN=ERROR 

FWACBAR=TCAFCAA; 



INITIATE BROWSE 



GO TO ERROR LABEL IF ERROR 



ERROR: 
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Forward Browse (TYPE=GETNEXT) 



The format of the DFHFC macro instruction to retrieve the next record in 
ascending sequence during a browse operation is shown below. 




TYPE=GETNEXT 

[ ,SEGSET={symbolic name | YES | ALL} ] 

[ ,DUPKEY=symbolic address] 

[ , NORESP=symbolic address] 

[ , ERROR=symbolic address] 

[ , SEGIDER=symbolic address] 

[ ,NOTFND=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,IOERROR=symbolic address] 

[ , NOTOPEN=symDolic address] 

[ ,ENDFILE=symbolic address] 

[ ,ILLOGIC=symbolic address] 



-VSAM & assembler 



This instruction can also be used to perform skip-sequential 
processing upon a VSAM data set. After a DFHFC TYPE=SETL macro 
instruction has been issued to initiate a browse operation, the next (or 
first) record in ascending sequence can be obtained by issuing the DFHFC 
TYPE=GETNEXT macro instruction* When the first GETNEXT request is 
issued following a SETL request for an ISAM data set, CICS/VS acquires 
the first record with a key equal to or greater than the key presented 
by a previous SETL; for a DAM data set, CICS/VS acquires the first 
record specified by the user. Each subsequent GETNEXT request, whether 
for an ISAM or a DAM data set, causes CICS/VS to acquire the next record 
in ascending sequence. When ISAM is used, records that are flagged for 
deletion are presented to the application program, which must be able to 
recognize them* 

When VSAM is used, a browse operation can be specified to begin at a 
particular relative byte location or with a record identified by a key. 
In the former case, the first GETNEXT request retrieves that record. 
Each succeeding GETNEXT retrieves the next record in ascending sequence. 

If a key is specified for a VSAM data set, it may be either specific 
or generic, and the application programmer can specify that the search 
begin (1) at a record having a key equal to the specific or generic key, 
or (2) at a record having a key equal to or greater than the specific or 
generic key. The effects of GETNEXT macro instructions are as described 
below* 

Before issuing the DFHFC TYPE=GETNEXT macro instruction, the 
application programmer must place the address of the FWA associated with 
the particular operation in TCAFCAA. If the application program has 
initiated multiple browse operations, it must keep track of the FWA 
associated with each operation and refer to a specific FWA when 
requiring services related to that browse* Similar requirements apply 
to the address of a specific VSWA in locate— mode processing of VSAM 
nonsegmented records* 

CICS/VS performs the following services in response to a DFHFC 
TYPE=GETNEXT macro instruction referring to an ISAM, VSAM, or DAM data 
set: 

1. Retrieves the next sequential record and places it in the FWA 
specified by the user at TCAFCAA 
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2. Places the identification (key, block identification, or the like) 
of the record just retrieved into the record identification field 
specified in the DFHFC TYPE=SETL request initiating the browse 

If the user issues a DFHFC TYPE=GET,TYPOPER=UPDATE request on the 
record returned in response to a DFHFC TYPE=GETNEXT request, the address 
of the record identification field can be specified in the DFHFC 
TYPE=GET request. 

The first DFHFC TYPE=GETNEXT macro instruction referring to a VSAM 
data set retrieves the record located in response to the DFHFC TYPE=SETL 
instruction initiating the browse. On a subsequent GETNEXT, CICS/VS 
checks the contents of the record identification field set aside for 
records of the data set. If this field contains the identification of 
the record previously received, CICS/VS retrieves the next logical 
record in sequence and places the identification of that record in the 
record identification field. Sequential retrieval such as described 
above for ISAM and DAM data sets then occurs. 

It is possible, however, when using VSAM data sets, for the 
application programmer to utilize a skip— sequential processing 
capability. All that is needed is to place the identification of the 
next record desired into the record identification field prior to 
issuing a GETNEXT request. If, upon checking this field, CICS/VS 
determines that its contents have been changed by the application 
program, CICS/VS accesses the record having the identification currently 
stored in the record identification field. This record need not be the 
next sequential record in the data set* This skip-sequential processing 
capability is available only for VSAM data sets. 

When VSAM skip— sequential processing is used, the record 
identification placed in the record identification field before issuing 
the GETNEXT request must be of the same form as that specified in the 
SETL or last RESETL request for this browse operation. That is, if the 
SETL or last RESETL specified a generic key, then the new record 
identification must be a generic key. It need not be the same length as 
that specified in the SETL or last RESETL. If the SETL or last RESETL 
specified an RBA, the new identification must be an RBA. Note that if 
the SETL or last RESETL specified an equal search (FKEQ or GKEQ) , a 
GETNEXT request using skip— sequential processing may result in a NOTFND 
(record not found) condition. 

In addition, CICS/VS can perform the following services, depending on 
the operands included in the DFHFC TYPE=GETNEXT macro instruction. 

1. Present the user with segments as specified in the GETNEXT request. 

2. Present the user with segments as specified in the SETL request if 
no segment set is specified in the GETNEXT request. 

3* If the FWA is not large enough to process a segment set specified 
in the GETNEXT request, dispose of the old FWA and acquire a new 
one large enough to process the new request* 

If the NOTFND condition occurs during a browse operation, the 
application program must issue either a RESETL macro to reset the browse 
or an ESETL macro to terminate the browse* Both these macros are 
discussed later in this chapter. 

The following examples show how to initiate a browse operation and 
retrieve selected segments from successive records of the data set. 
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For Assemble r language : 

COPY DFHTCADS 

KBYF DS 8X 

FWACBAR EQU 7 

COPY DFHFWADS 

RECORDA DS 0CL350 



COPY TCA SYMBOLIC STRG DEFN 

DEFINE KEY FIELD IN TWA 

ASSIGN FWA BASE REGISTER 

COPY CICS/VS CONTROL SECTION OF FWA 

DEFINE RECORD LAYOUT IN FWA. 



J 

J 

CSECT 

MVC KEYF (8) ,=8X»00« 
INITIAL DFHFC TYPE=SETL / 

DATASET=MASTER / 

SEGSET=A / 

RDIDADR=KEYF 

L FWACBAR, TCAFCAA 



START AT BEGINNING OF DATA SET 
INITIATE BROWSE 

SET DEFAULT SEGMENT SET 

ESTABLISH FWA BASE REGISTER 



i 

ST FWACBAR, TCAFCAA 

DFHFC TYPE=GETNEXT 

L FWACBAR,TCAFCAA 



RESTORE FWA ADDRESS 

GET NEXT SEQUENTIAL RECORD 

ASSURE ADDRESSABILITY IF SEGMENTED 



ST FWACBAR, TCAFCAA 
DFHFC TYPE=GETNEXT, 

SEGSET=B 
L FWACBAR, TCAFCAA 



RESTORE FWA ADDRESS 

GET NEXT RECORD 

WITH SEGMENT B 

ASSURE ADDRESSABILITY IF SEGMENTED 
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For COBOL : 

02 FWACBAR PIC S9(8) COMP* 

01 DFHTCADS COPY DFHTCADS. 
02 KEYF PIC S9(18) COMP. 



NOTE DEFINE BASE REGISTER FOR FWA. 
NOTE COPY SYMBOLIC STRG DEFN FOR TCA * 
NOTE DEFINE KEY FIELD IN TWA. 



01 DFHFWADS COPY DFHFWADS. 
02 RECORD PIC X (350) . 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA. 
NOTE DEFINE RECORD LAYOUT IN FWA. 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR. 



NOTE ESTABLISH TCA ADDRESSABILITY i 



MOVE TO KEYF. 



NOTE START AT BEGINNING OF DATA SET. 



INITIAL . 

DFHFC TYPE=SETL, 

DATASET=MASTER, 
SEGSET=A, 
RDIDADR=KEYF 
MOVE TCAFCAA TO FWACBAR. 



INITIATE BROWSE 

SET DEFAULT SEGMENT SET 

NOTE ESTABLISH FWA ADDRESSABILITY. 



MOVE FWACBAR TO TCAFCAA* 

DFHFC TYPE=GETNEXT 
MOVE TCAFCAA TO FWACBAR. 



GET NEXT SEQUENTIAL RECORD. 



MOVE FWACBAR TO TCAFCAA. 
DFHFC TYPE=GETNEXT, 
SEGSET=B 
MOVE TCAFCAA TO FWACBAR. 



GET NEXT RECORD 

WITH SEGMENT B 

NOTE POSSIBLE NEW FWA. 
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F or PL/I ; 

^INCLUDE DFHTCADS; 
02 KEYF CHAR (8); 



/*COPY SYMBOLIC STRG DEFN FOR TCA*/ 
/♦DEFINE KEY FIELD IN TWA*/ 



^INCLUDE DFHFWADS; 

02 RECORD CHAR (350) ; 



/*COPY SYMBOLIC STRG DEFN FOR FHA*/ 
/♦DEFINE RECORD LAYOUT IN FWA*/ 



KEYF=LOtf (8) ; 



/♦START AT BEGINNING OF DATA SETV 



INITIAL: 

DFHFC TYPE=SETL, 

DA TASET=M ASTER, 

SEGSET=A, 

RDIDADR=KEYF 

FWACBAR=TCAFCAA; 



INITIATE BROWSE 

SET DEFAULT SEGMENT SET 

/♦ESTABLISH FWA ADDRESSABILITY^/ 



TCAFCAA=FWACBAR; 

DFHFC TYPE=GETNEXT 
FWACBAR=TCAFCAA; 



GET NEXT SEQUENTIAL RECORD 



TCAFCAA=FWACBAR; 

DFHFC TYPE=GETNEXT, 
SEGSET=B 
FWACBAR=TCAFCAA; 



GET NEXT RECORD 
WITH SEGMENT B 
/♦POSSIBLE NEW FWAV 
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Backward Browse, VSAM and Assembler Language Only 
TYPE=GETPREV) 

The format of the DFHFC macro instruction to retrieve the next record in 
descending sequence during a browse operation is shown below. The DFHFC 
TYPE=GETPREV macro can be used only in an assembler language application 
program and on a VSAM data set. 




TYPE=GETPREV 

[ , SEGSET= {symbolic name | YES | ALL} ] 

[ ,DOPKEY=symbolic address] 

[ ,NORESP=symbolic address] 

[ ,ERROR=symbolic address] 

[ ,SEGIDER=symbolic address] 

[ ,NOTFND=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,IOERROR=symbolic address] 

[ ,NOTOPEN=symbolic address] 

[ ,ENDFILE=symbolic address] 

[ ,ILLOGIC=symbolic address] 



After a DFHFC TYPE=SETL macro instruction has been issued to initiate 
a browse operation, the next (or first) record in descending seguence 
can be obtained by issuing the DFHFC TYPE=GETPREV macro instruction* 

A browse operation can be specifed to begin at a particular relative 
byte location or with a record identified by a key. In the former case, 
the first GETPREV reguest retrieves that record. Each succeeding 
GETPREV retrieves the next record in descending sequence* 

If a key is specified for a VSAM data set, it must be specific, and 
the application programmer can specify that the search begin at a record 
having a key equal to the specified key. The effects of GETPREV macro 
instructions are as described below. 

Before issuing the DFHFC TYPE=GETPREV macro instruction, the 
application programmer must place the address of the FWA associated with 
the particular operation in TCAFCAA. If the application program has 
initiated multiple browse operations, it must keep track of the FWA 
associated with each operation and refer to a specific FWA when 
requiring services related to that browse* Similar requirements apply 
to the address of a specific VSHA in locate— mode browsing of VSAM 
nonsegmented records. 

CICS/VS performs the following services in response to a DFHFC 
TYPE=GETPREV macro instruction referring to a VSAM data set: 

1 . Retrieves the next record in descending sequence and places it in 
the FWA specified by the user at TCAFCAft 

2. Places the identification (key, or relative byte address) of the 
record just retrieved into the record identification field 
specified in the DFHFC TYPE=SETL request initiating the browse 

If the user issues a DFHFC TYPE=GET,TYPOPER=UPDATE request on the 
record returned in response to a DFHFC TYPE=GETPREV request, the address 
of the record identification field can be specified in the DFHFC 
TYPE=GET request. 
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The first DFHPC TYPE=GETPREV macro instruction retrieves the record 
located in response to the DPHFC TYPE=SETL instruction initiating the 
browse. On a subseguent GETPREV, CICS/VS checks the contents of the 
record identification field set aside for records of the data set. If 
this field contains the identification of the record previously 
received, CICS/VS retrieves the next logical record in seguence and 
places the identification of that record in the record identification 
field. 

If the DFHPC TYPE=GETPREV macro instruction is issued following a 
DFHFC TYPE=SETL macro instruction using a generic key, an invalid 
request will be indicated. 

In addition, CICS/VS can perform the following services, depending on 
the operands included in the DFHFC TYPE=GETPREV macro instruction. 

1. Present the user with segments as specified in the GETPREV request. 

2. Present the user with segments as specified in the SETL request if 
no segment set is specified in the GETPREV reguesti 

3. If the FWA is not large enough to process a segment set specified 
in the GETPREV reguest, dispose of the old FWA and acquire a new 
one large enough to process the new request. 
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Terminate Browse (TYPE=ESETL) 



The format of the DFHFC macro instruction to terminate a browse 
operation on a data set is as follows: 




DFHFC | TYPE=ESETL 

| [ ,NORESP=symbolic address] 

| [ ,ERROR=symbolic address] 

| [ ,INVREQ=symbolic address] 

| [ ,ILLOGIC=symbolic address] 



-VSAM 



Before this macro is issued, the programmer must ensure that TCAFCAA 
contains the address of the file work area (FWA) associated with the 
browse operation he wishes to terminate. When locate— mode processing of 
VSAM nonsegmented records is utilized, TCAFCAA must contain the address 
of the VSWA associated with the browse operation being terminated. In 
response to an ESETL request, CICS/VS releases all I/O and work areas 
associated with the browse operation. 

The following examples show how to terminate two concurrent browse 
operations. 



F or Assembler langua ge : 



COPY 
FWACELL1 DS 


DFHTCADS 
A 


FWACELL2 DS 


A 


FWACBAR EQU 

COPY 
RECORD DS 


7 

DFHFWADS 
0CL3 50 



COPY TCA SYMBOLIC STRG DEFN 
CONTAINS ADDR OF FWA USED 
FOR FIRST BROWSE OPERATION 
CONTAINS ADDR OF FWA USED 
FOR SECOND BROWSE OPERATION 
ASSIGN FWA BASE REGISTER 
DEFINE FWA SYMBOLIC STORAGE DEFN 
DEFINE RECORD 



CSECT 



MVC TCAFCAA, FWACELL1 

DFHFC TYPE=ESETL 

MVC TCAFCAA, FCACELL2 

DFHFC TYPE=ESETL 



MOVE BROWSE 1 FWA ADDR TO TCA 

ISSUE ESETL MACRO INSTRUCTION 

MOVE BROWSE 2 FWA ADDR TO TCA 

ISSUE ESETL MACRO INSTRUCTION 
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For COBOL ; 

02 FWACBAR PIC S9 (8) COMPi 



01 DFHTCADS COPY DFHTCADS. 

02 FWACELL1 PIC S9 (8) COMP, 
2 FWACELL2 PIC S9 (8) COMP, 

01 DFHFWADS COPY DFHFWADS* 
02 RECORD PIC X (350) . 



NOTE DEFINE BASE REGISTER FOR FWA. 
NOTE COPY SYMBOLIC STRG DEFN FOR TCA 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA, 
NOTE DEFINE RECORD LAYOUT IN FWA. 



MOVE FWACELL1 TO TCAFCAA. 
DFHFC TYPE=ESETL 



NOTE PREPARE TO END FIRST BROWSE. 
TERMINATE FIRST BROWSE 



MOVE FWACELL2 TO TCAFCAA. 
DFHFC TYPE=ESETL 



NOTE PREPARE TO END 2ND BROWSE* 
TERMINATE SECOND BROWSE. 



F or PL/I ; 

% INCLUDE DFHTCADS; 

02 FWACELL1 POINTER; 
02 FWACELL2 POINTER; 



/♦COPY SYMBOLIC STRG DEFN FOR TCA*/ 



^INCLUDE DFHFWADS; 

02 RECORD CHAR (350); 



/♦COPY SYMBOLIC STRG DEFN FOR FWA*/ 
/♦DEFINE RECORD LAYOUT IN FWA*/ 



TCAFCAA=FWACELL1 ; 

DFHFC TYPE=ESETL 
TCAFCAA=FWACELL2 ; 

DFHFC TYPE=ESETL 



/♦MOVE BR0WSE1 FWA ADDR TO TCA*/ 
/♦MOVE BROWSE2 FWA ADDR TO TCA*/ 
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Reset Browse (TYPE=RESETL) 



The format of the DFHFC macro instruction to reset the search argument, 
default segment set name, and/or type of search argument (VSAM only) for 
a browse operation is as follows: 




TYPE=RESETL 
,SEGSET= {symbolic name | YES | ALL} ] 
r ARGTY P= (KEY | RBA) ] < 



, SRCHTYP= f FKEQ I FKGE I GKEQ I GKGE1 ] 
,NORESP=symbolic address] 
,ERROR=symbolic address ] 
, SEGIDER=symbolic address] 
, NOTFND=symbolic address] 
,INVREQ=symbolic address] 
,IOERROR=symbolic address] 
,NOTOPEN=symbolic address] 
,ILLOGIC=symbolic address] <— 



-VSAM 
-VSAM 



-VSAM 



Once a browse operation has 
programmer may, at any time pr 
browse, reset the search argum 
sequential record in the data 
(for a VSAM data set) the type 
records can also be reset by i 
instruction. Prior to issuing 
should place the address of th 
record identification in the r 
the original SETL request; 



been initiated, the application 
ior to issuing an ESETL request for the 
ent to some record other than the next 
set. The default segment set name and 

of search argument used in retrieving 
ssuing the DFHFC TYPE=RESETL macro 

the request, the application programmer 
e appropriate FWA into TCAFCAA and the new 
ecord identification field specified in 



The use of the RESETL macro instruction allows the application 
programmer to avoid issuing an ESETL request followed by another SETL 
request, and causes CICS/VS to use the same I/O and work area. Upon 
return from the RESETL request, TCAFCAA contains the address of a new 
FWA that the user can use for the browse operation. 

The RESETL request allows the user to "skip" through his data set in 
a browse operation with ease. A similar capability is available to VSAM 
users through the GETNEXT instruction. 

A browse operation should be terminated by issuing a TYPE=ESETL 
macro, but a normal or abnormal end of task will also terminate a 
browse. 

The following examples show how to reset the search argument and the 
default segment set for a browse operation. 



For Assemble r lang ua g e : 





COPY 


DFHTCADS 


KEYF 


DS 


D 


FWACBAR 


EQO 


7 




COPY 


DFHFWADS 


REC0RD1 


DS 


0CL350 



COPY TCA SYMBOLIC STRG DEFN 
DEFINE KEY FIELD IN TWA 
ASSIGN FHA BASE REGISTER 
COPY FWA DSECT 
DEFINE RECORD WITH SEGSET A 



ORG REC0RD1 
REC0RD2 DS 0CL250 



DEFINE RECORD WITH SEGSET B 
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GSECT 

MVC KEYF(8) ,=8X»00» 

DFHFC TYPE=SETL, 

DATASET=MASTER, 

RDIDADR=KEYF, 

SEGSET=A 

L FWACBAR, TCAFCAA 



INITIALIZE KEY FIELD 

ISSUE INITIAL SETL MACRO 

FOR DATA SET "MASTER" 

INITIAL SEARCH ARG=0 

FOR SEGSET=A 

ESTABLISH ADDRESSABILITY TO FWA 



ST FWACBAR, TCAFCAA 
MVC KEYF(8) ,=CL8»SMITH» 
DFHFC TYPE=RESETL, 

SEGSET=B 
L FWACBAR, TCAFCAA 



STORE FWA ADDR IN TCA 

ESTABLISH NEW SEARCH ARGUMENT 

ISSUE RESETL MACRO * 

NEW SEGSET ID 

ESTABLISH ADDRESSABILITY TO FWA 



For COBOL: 



02 FWACBAR PIC S9 (8) COMP. 



01 DFHTCADS COPY DFHTCADS. 
02 KEYF PIC S9(18) COMP. 

02 FILLER REDEFINES KEYF. 
03 KEYC PIC X(8) . 



NOTE DEFINE BASE REGISTER FOR FWA. 
NOTE COPY SYMBOLIC STRG DEFN FOR TCA. 
NOTE DEFINE KEY FIELD IN TWA. 



01 DFHFWADS COPY DFHFWADS 
02 RECORD1 PIC X (350) . 



NOTE COPY SYMBOLIC STRG DEFN FOR FWA, 
NOTE DEFINE RECORD WITH SEGSET A. 



01 DFHFHA REDEFINES DFHFWADS, 
02 FILLER PIC X (16) . 
02 RECORD2 PIC X (250) . 



NOTE CREATE STRG DEFN FOR FWA. 

NOTE LENGTH OF FWA. 

NOTE DEFINE RECORD WITH SEGSET B. 



MOVE TO KEYF. 

DFHFC TYPE=SETL, 

DATASET=MASTER, 

RDIDADR=KEYF, 

SEGSET=A 

MOVE TCAFCAA TO FWACBAR. 



ISSUE INITIAL SETL MACRO INSTR * 
FOR DATA SET "MASTER" * 

INITIAL SEARCH ARG=0 * 

FOR SEGSET=A 
NOTE ESTABLISH ADDRESSABILITY TO FWA. 



MOVE FWACBAR TO TCAFCAA . 
MOVE 'SMITH* TO KEYC. 
DFHFC TYPE=RESETL, 

SEGSET=B 
MOVE TCAFCAA TO FWACBAR. 



NOTE STORE FWA ADDRESS IN TCA. 

NOTE ESTABLISH NEW SEARCH ARGUMENT. 

ISSUE RESETL MACRO INSTRUCTION * 

NEW SEGSET ID 

NOTE ESTABLISH ADDRESSABILITY TO FWA. 
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For PL/I ; 

XINCLUDE DFHTCADS; 
02 KETF CHAR (8) ; 



/*COPY SYMBOLIC STRG DEFN FOR TCA*/ 
/♦DEFINE KEY*/ 



XINCLUDE DFHFWADS; 

02 RECORD1 CHAR (350); 
DECLARE 01 DFHXFWA BASED (FWACBAR) , 

02 FILL CHAR (16) , 

02 RBCORD2 CHAR (250) ; 



/♦COPY SYMBOLIC STRG DEFN FOR FWA*/ 
/♦DEFINE RECORD WITH SEGSET A*/ 

/♦LENGTH OF FWA*/ 

/*DEFINE RECORD WITH SEGSET B*/ 



KEYF=LOW(8) ; 

DFHFC TYPE=SETL, 

DATASET=MASTER, 

RDIDADR=KEYF, 

SEGSET=A 

FWACBAR=TCAFCAA; 



/♦SET KEY VALUE TO ZERO*/ 
ISSOE INITIAL SETL MACRO INSTR * 

FOR DATA SET "MASTER" * 

INITIAL SEARCH ARG EQUALS ZERO * 

FOR SEGSET A 
/♦ESTABLISH ADDRESSABILITY FOR FWA*/ 



TCAFCAA=FWACBAR; 
KEYF= •SMITH 1 ; 

DFHFC TYPE=RESETL, 
SEGSET=B 
FWACBAR=TCAFCAA; 



/*STORE FWA ADDR IN TCA*/ 
/♦ESTABLISH NEW SEARCH ARGUMENT*/ 
ISSUE RESETL MACRO INSTRUCTION * 

NEW SEGSET ID 
/♦ESTABLISH ADDRESSABILITY TO FWAV 
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Test Response to a Request for File Services (TYPE=CHECK) 

The format of the DFHFC macro instruction to test the CICS/VS response 
to a preceding DFHFC request for file services is as follows: 




TYPE=CHECK 

[ ,NORESP=symbolic address] 
[ , ERROR=symbolic address] 
[ ,DSIDER=symbolic address] 
[ ,SEGIDER=symDolic address] 
[ ,NOTFND=symbolic address] 
[ ,DUPKEY=symbolic address] 
[ , DUPREC=symbolic address] 
[ ,INVREQ=symbolic address] 
[ ,IOERROR=symbolic address] 
[ ,DUPDS=symbolic address] 
[ ,NOSPACE=symbolic address] 
[ ,NOTOPEN=symbolic address] 
[ ,ENDFILE=symbolic address] 
[ ,ILLOGIC=symbolic address] 



-VSAM 6 assembler 



-VSAM 



I File Control Response Codes 



I To test a response code the application programmer must know (1) the 
CICS/VS response codes and their meanings, and (2) the symbolic labels 
by which he can refer to the response codes. These are shown in Figure 
3.2—11* If the Assembler— language or PL/I programmer elects to check 
for a particular response-code bit pattern, he can access the response 
code at TCAFCTR. The COBOL programmer who elects to check for a 
particular response-code bit pattern, can access the response code at 
TCAFCRC. 

Because the multipunch codes to be checked in a COBOL program 
commonly correspond to unprintable characters, an alternative facility 
is provided in CICS/VS for use by the COBOL programmer. He can evaluate 
the response by referring to the condition names generated by CICS/VS 
(for example, FCNORESP) . Use of this approach is illustrated in the 
| examples at the end of this discussion. 
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1 

| File Services I 
I Request by 
| DFHFC Macro | 
I Instruction | 


Condition | 


1 

Response Code j 


i 
Assembler | 


COBOL 1 | 


PL/I | 


| All 


NORESP | 
(Normal 
Response) | 


X«00» | 


LOW-VALUES | 
(FCNORESP) | 


00000000 | 


| GET, DELETE, GETAREA, | 
| SETL, CHECK 


DSIDER | 
(Data set 
identific— | 
ation er— | 
ror) | 


X»01« | 


12-1-9 | 

(FCDSIDER) | 


00000001 | 


| GET, PUT, DELETE, SETL, 
| GETNEXT,RESETL, CHECK, 
| GETPREV 


ILLOGIC | 
(VSAM only;| 
error not 
covered by 
any other 
code) 


X»02« 


12-2-9 
(FCILLOGIC) | 


00000010 | 


| GET, SETL, GETNEXT, 

| RESETL, CHECK, GETPREV 


SEGIDER2 
(Segment 
set identi- 
fication 
error) 


X«04« | 


12-4-9 
(FCSEGIDER) 


00000100 | 


| All 


INVREQ 
(Invalid 
Request) 


X»08» 


12-8-9 
(FCINVREQ) 


00001000 | 


| GET, CHECK 


DUPDS 3 
(Duplicate 
data set) 


X»0A» 


12-2-8-9 
(FCDUPDS) 


00001010 | 


| GET, PUT, DELETE, 

| GETAREA, SETL, GETNEXT, 

| RESETL, CHECK, GETPREV 


NOTOPEN 
(Data set 
not open) 


X'OCV 


12-4-8-9 
| (FCNOTOPEN) 


00001100 | 


| GETNEXT, CHECK, GETPREV 


ENDFILE 
(End of 
file during 
browse) 


X»0F» 


12-7-8-9 

| (FCENDFILE) 


00001111 | 


| GET, PUT, DELETE, SETL, 
| GETNEXT, RESETL, CHECK, 
| GETPREV 


| lOERROR 
I (Error not 
I covered by 
| any other 
I code) 


| X«80« 


j 12-0-1-8 
| (FCIOERROR) 


| 10000000 | 


| GET, DELETE, SETL, 

| GETNEXT, RESETL, CHECK, 

| GETPREV 


| NOTFND* 
| (Record not 
found) 


| X»81» 


| 12-0-1 

| (FCNOTFND) 


| 10000001 | 


| PUT, CHECK 


| DUPREC 

| (Duplicate 

I records) 


| X»82» 


| 12-0-2 

| (FCDUPREC) 


| 10000010 | 



Figure 3-2—11. (Part 1 of 2) File Control Response Codes 
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I File Services | | I 
j Request by | j Response Code | 

1 rn?FfT?r" Mnrrn 1 1 — 1 


| Instruction | Condition | Assembler \ COBOL 1 | PL/I | 


| PUT, CHECK | NOSPACE 5 | X»83» | 12-0-3 | 10000011 | 
| | (No DASD | | (PCNOSPACE) | | 
| | space for j j j j 
I I adding | | | | 
| | record) | | j | 

| GET,GETNEXT,GETPREV, | DUPKEY | X»8U» | - | - | 
| CHECK | (VSAM & I I I I 
| I assembler j | | | 
| | only; dup— | | | | 
| | licate key | | | j 
| | in altern— | | | | 
| | ate index) | | | | 

I All | ERROR | See Note | See Note 6 |See Note 6| 
I I (Any | 6 j | j 
| I response | | | | 
| | other than | | | | 
| | NORESP) || || 


I Notes: I 

| 1. The names enclosed in parentheses in the COBOL column | 
I indicate the condition names generated by CICS/VS. These | 
| names may be used in testing for the respective | 
I conditions in a COBOL program. I 

j 2. The SEGIDER condition can occur only when the SEGSET operand | 
| is specified. I 

I 3. The DUPDS condition can occur only when the INDEX operand is j 
I specified. I 

| 4. For SETL, GETNEXT, GETPREV, or RESETL, the NOTFND condition | 
I can occur only for VSAM files. | 

| 5. The NOSPACE condition can occur only when TYPOPER=NEWREC is | 
| specified. j 

| 6. The test for the ERROR response is satisfied by a not equal j 
I condition; that is, not X»00», not LOW-VALUES, or not 00000000 | 
| for Assembler, COBOL, and PL/I, respectively. | 



Figure 3i2— 11* (Part 2 of 2) File Control Response Codes 

The keyword operands that can be used to request tests of the 
response to a request for file services (that is, a DFHFC macro 
instruction) are identified in the discussions of the instruction 
formats. The condition expressed by each keyword is explained in detail 
and should be referred to by the application programmer when using any 
of the checking methods described above. 

When certain exception conditions (for example, NOTFND, IOERROR, OR 
DUPREC) occur, the FIOA or VSWA that has been acquired for the file 
control reguest, is retained. Its address is available to the 
application program. Before other file control reguests are issued, the 
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storage occupied by the FIOA or VSWA should be freed by a DFHFC 
TYPE=RELEASE macro instruction. When the exception conditions DSIDER, 
SEGIDER, INVREQ, or NOTOPEH occur no storage areas are acquired for the 
associated file control request. 

The following examples show how to examine the response code provided 
by CICS/VS at TCAFCTR (for Assembler language or PL/I) or TCAFCRC tfor 
COBOL) and transfer control to an appropriate user— written error- 
handling routine. The alternative approach available to COBOL 
programmers is also shown. 



For Assembler language ; 



DFHFC 


TYPE=GET, 

DAT ASET=M ASTER, 

RDIDADR=KEYF 




CLI 


TCAFCTR ,X»00» 


NORMAL RESPONSE 


BE 


GOOD 




CLI 


TCAFCTR, X«80» 


I/O ERROR 


BE 


ERROR 




CLI 


TCAFCTR,X»08» 


INVALID REQUEST 


BE 


ERROR 





GOOD 



DS 



OH 



ERROR DS OH 

DFHPC TYPE=ABEND 



For COBOL: 



DFHFC TYPE=GET, 

DATASET=MASTER, 

RDIDADR=KEYF 
IF TCAFCRC = LOW-VALUES GO TO GOOD 
IF TCAFCRC = • » GO TO ERROR. 
IF TCAFCRCY= • • GO TO ERROR * 



NOTE LOW-VALUES NORESP 
NOTE 12-0-1-8 IOERROR 
NOTE 12-8-9 INVREQ. 



GOOD. 



ERROR. 



DFHPC TYPE=ABEND 

where the value specified within single quotation marks is an 
unprintable multipunch code for the required hexadecimal value. 
For example, a hexadecimal 80 has a multipunch code of 12—0—1- 
8. 
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The alternative approach to response code checking, which is 
available to COBOL programmers as described earlier, is 
generally a coding convenience and provides concise code 
documentation* When this approach is used, the IF statements 
above are replaced by statements of the form shown below, using 
the CICS/VS generated condition names: 



IP FCNORESP THEN GO TO GOOD. 
IF FCIOERROR THEN GO TO ERROR. 
IF FCINVREQ THEN GO TO ERROR. 



For PL/I ; 



DFHFC TYPE=GET, * 

DATASET=MASTER, * 

RDIDADR=KEYF 
IF TCAFCTR= , 00000000 , B THEN GO TO GOOD; /* NORMAL RESPONSE */ 
IF TCAFCTR=» 10000000 "B THEN GO TO ERROR; /* I/O ERROR */ 
IF TCAFCTR=» 00001 000 "B THEN GO TO ERROR; /* INVALID REQUEST */ 



GOOD: 



ERROR: 

DFHPC TYPE=ABEND 
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Operands of DFHFC Macro 

ARGTYP= 

describes the contents of the record identification field when 
operating on a VSAM data set. 

KEY 

indicates that the record identification field contains a 
search key or a relative record number. 

indicates that the record identification field contains a 
relative byte address. 

In a DFHFC TYPE=GETAREA macro, the ARGTYP operand can only 
be used when TYPOPER=MASSINSERT is also specified. ARGTYP 
describes the record identification fields of the records 
to be mass-inserted by DFHFC TYPE=POT macros* When used in 
a mass— insert operation, the ARGTYP operand cannot be 
overriden* 

DATASET=symbolic name 

is the symbolic name of the data set to be accessed* When 
indirect accessing is involved, this is the name of the primary 
data set (see "Indirect Accessing" earlier in this chapter) . 
The name must appear in the file control table (FCT). If this 
operand is omitted, the symbolic name is assumed to be in 
TCAFCDI . 

DSIDER=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the data set specified by the 
DATASET operand (or at TCAFCDI) cannot be located in the FCT. 
The error also occurs if the data set specified in the INDEX 
operand of a DFHFC TYPE=GET macro instruction (or at TCAFCAI) , 
or any of the lower— level data sets in the indirect accessing 
hierarchy, cannot be found in the FCT. DSIDER signifies "data 
set identification error." The contents of TCAFCAA are not 
meaningful. 

DUPDS=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the record retrieved on an indirect 
access is from a duplicates data set rather than from the 
primary data set. The user's routine can include provisions 
for processing the duplicate record. DUPDS signifies 
"duplicates data set." 

TCAFCAA contains: 

• The address of an FIOA if the duplicates data set is 
unblocked and its records are non— VSAM 

• The address of an FWA if the duplicates data set is blocked 
or in all cases where records are VSAM. 
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DUPKEY=symbolic address 

• valid only for assembler language application programs and 
VSAM data sets. 

specifies the entry label of the user— written routine to which 
control is to be passed if the duplicate key condition is 
raised. This can only occur with VSAM data sets where records 
are being accessed by alternate indexes. This condition 
indicates that a record has been retrieved but that there are 
other records in the data set which have the same (alternate) 
key^ These records can be retrieved by a browse. 

DDPREC=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an attempt is made to add a record 
to a data set in which a record with the same key already 
exists* DUPREC signifies "duplicate record." 

TCAFCAA contains: 

• The address of an FIOA if the PUT request is against an 
ISAM data set 

• The address of a VSWA if the PUT request is against a VSAM 
data set 

The FWA will be released by the File Control Program. After 
any interrogation of the FIOA or VSHA returned is complete, the 
program should issue a DFHFC TYPE=RELEASE macro instruction. 

EtfDFILE=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an end-of— file condition is detected 
during the sequential retrieval (browse) of records in a data 
set. This condition can occur only in response to a GETNEXT 
request* TCAFCAA contains the address of the FWA for the 
browse operation if move mode is specified or implied in the 
SETL request. TCAFCAA contains the address of the VSWA that 
represents the browse if locate mode is specified. 

ERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if any error occurs on a file 
operation. The CICS/VS response code should be further 
interrogated in this user— written routine. 

ILLOGIC=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be transferred if a VSAM error that does not fall 
within one of the other CICS/VS response categories occurs. 
TCAFCAA contains the address of a VSffA. The user»s routine may 
check the actual logical error codes in the RPL which is at 
VSWARPL. The error code is at VSWAERRC, and the return code is 
at VSWARTNC. 

After an interrogation of the area returned, the program should 
issue a DFHFC TYPE=RELEASE macro instruction. 
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INDEX= 



indicates that indirect accessing is to be used and specifies 
the symbolic name of the highest level index data set to be 
used. (This index data set is the first data set accessed in 
the hierarchy.) 

symbolic name 

is the symbolic name of the highest level index data set to 
be accessed. The name must have been defined in the FCT. 

YES 

indicates that the symbolic name of the highest level index 
data set has been placed in TCAFCAI. 

If the data set identified by this operand is a DAM data set, 
it cannot be blocked i 



INITIMG= 



specifies a one— byte (two-digit) hexadecimal initialization 
value for the FWA* 

value 

is a two-digit hexadecimal numeral to be used as the 
initialization value* 

YES 

indicates that the hexadecimal initialization value has 
been placed in TCASCIB. 

If this operand is omitted, the FWA is initialized to EBCDIC 
blanks (X«40»). 

INVREQ=symbolic address 

specifies the entry label of the user-written routine to which 
control is to be passed if the attempted file operation is not 
provided for or allowed according to the data set entry 
specification in the FCT* INVREQ signifies "invalid request." 

TCAFCAA contains: 

• A n on— zero value if the request is not allowed according to 
the FCT entry for the file* 

• Zero if the request is invalid or if the code to support 
the request has not been generated into the CICS/VS file 
control program. 

IOERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an input/output error occurs during 
a file operation. When an I/O event error code is not covered 
by one of the CICS/VS error classes (for example, by NOSPACE or 
NOTFND) , it is considered to be an 1/0 error. 

TCAFCAA contains: 

• The address of an FIOA if the request is against an ISAM or 
a DAM data set 
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• The address of a VSWA if the request is against a VSAM data 
set 

The application programmer should be aware of the following 
considerations: 

• For an ISAM or DAM data set, the actual error codes may be 
checked in the PIOA by the user's routine (FCPIOEX for ISAM 
and FCFIOBBX for DAM) . Because of access method and 
operating system dependencies, checks for these codes may 
have a limiting effect on the usability of an application 
program in varying environments, particularly if migration 
from CICS/DOS/VS to CICS/OS/VS becomes desirable* 

• For a VSAM data set, the actual error codes may be checked 
in the request parameter list (RPL) located at VSWARPL. 
The error code is at VSWAERRC, and the return code is at 
VSWARTNC* Because of access method and operating system 
dependencies, checks for these codes may have a limiting 
effect on the usability of an application program in 
varying environments, particularly if migration from 
CICS/DOS/VS to CICS/OS/VS becomes desirable* 

• For RBSETL or GETNEXT the browse operation is still active, 
but the position in the data set may have been lost* A 
RESETL using the record identification for the next record 
required should be issued to reestablish the position in 
the data set* If move mode is specified or implied in the 
initiating SETL request, the FWA representing the browse 
operation must be used for the RESETL; if locate mode is 
specified in the SETL reguest, the VSWA must be used. 

• For POT, the FWA will have been released* 

Except for RESETL or GETNEXT, after any interrogation of 
| the area returned is complete, the program should issue a 

| DFHFC TYPE=RELEASE macro instruction* 



MODE= 



is used to specify the processing mode for a read-only or 
browse request to a VSAM data set. 

MOVE 

specifies move mode processing. Upon return to the 
application program, TCAFCAA contains the address of the 
FWA acquired for the read-only or browse operation. If the 
data set referred to contains variable— length records, the 
LLpjtf length field is included as part of the record* 

LOCATE 

specifies locate mode processing* Upon return to the 
application program, TCAFCAA contains the address of a 
VSWA. The address of the retrieved record is at VSWAREA. 
If the data set referred to contains variable— length 
records, the LL## length field is not retrieved as part of 
the record; instead, the length of the record is placed in 
VSWALEN. This parameter cannot be specified if 
TYPOPER=UPDATB is specified and/or segmented records are 
being retrieved* 
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NORESP=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if no error occurs on a file operation. 
NORBSP signifies "normal response." 

The field TCAFCAA in the TCA of the task contains: 

• The address of an FIOA after a read-only unsegmented GET 
against an unblocked non— VSAM data set or a blocked DAM 
data set if deblocking is not requested 

• The address of an FWA after a GET against a blocked data 
set, a GET segmented, a GET for update, a GETAREA , SETL, 
GETNEXT, or RESETL. An FWA is always acquired for VSAM 
move mode operations, regardless of blocking 

• The address of a VSWA after a locate— mode GET or SETL 
against a VSAM data set and after a GETNEXT or RESETL for a 
browse operation initiated by a locate— mode SETL 

• Meaningless information after a PUT, DELETE, RELEASE, or 
ESETL 

NOSPACE=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be transferred if no direct access space is 
available for adding records to a data set. This error 
condition is not applicable when adding records to a fixed- 
length DAM data set that does not contain keys. TCAFCAA 
contains the address of an FWA containing the record to be 
added. This FWA may be at a different storage location than 
the FWA passed with the PUT request. 

NOTFND=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an attempt to retrieve or delete a 
record based on the search argument provided is unsuccessful. 
NOTFND signifies "record not found." 

TCAFCAA contains: 

• The address of an FIOA if the request was a GET against an 
ISAM or a DAM data set 

• The address of a VSWA if the request was a GET, DELETE, 
SETL, RESETL, or GETNEXT request using skip— sequential 
against a VSAM data set 

The application programmer should be aware of the following 
considerations : 

• Except for RESETL or GETNEXT, the program should issue a 
DFHFC TIPE=RELEASE macro instruction when any interrogation 
of the area is complete. 

• For SETL, the browse operation was not initiated. 
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o For RESETL or GETNEXT, the browse operation is still 

active, but the position in the data set has been lost. A 
RESETL should be issued to reestablish the position in the 
data set. If move mode is specified or implied in the SETL 
request initiating the browse operation, the FWA 
representing the browse must be used for the RESETL; if 
locate mode is specified in the SETL reguest, the VSWA must 
be used. 

NOTOPEN=symbolic address 

specifies the entry label of the user-written routine to which 
control is to be transferred if the requested data set is not 
open* This error condition can occur in response to any file 
service reguest (except RELEASE and ESETL) , because a data set 
can be closed dynamically at any time without regard to 
outstanding activity on the data set. The contents of TCAFCAA 
are not meaningful. 

RDIDADR= 

specifies the symbolic address of the record identification 
field for a record, or the relative record number of a record. 

symbolic address 

is the symbolic address of the record identification field 
that contains the key (for ISAM) , the block reference (for 
DAM) , or the key, relative byte address, or the relative 
record number (for VSAM ) of the record to be processed. If 
this operand is omitted, the address is assumed to be in 
TCAFCRI. This field is used when adding a new record (for 
ISAM, DAM, and VSAM) or when updating an existing record in 
a nonkeyed DAM data set without previously reading it for 
update. 

Notes ; 

1. This operand must not refer to a field in the FWA, 

because the FWA might be freed before the write occurs. 

2* The DFHFC TYPE=PUT, TYPOPER=NEWREC macro instructions 
for a VSAM mass— insert operation may specify the same 
record identification field or different record 
identification fields. 

3. The key field (for ISAM) may be altered by the access 
method during the file operation. If a new key is to i 
derived by modifying the old key, the old key must 

be saved elsewhere before issuing the DFHFC macro. 

4. When adding a new record to a VSAM entry-seguence 
data set, there is no need to supply a relative byte 
address (RBA) . However, a field must be provided to 
receive the RBA after the record has been added; the 
address of the field must be supplied either in 
TCAFCRI or by using the RDIDADR operand. 
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relative record number 

is the number of the required record in a VSAM relative- 
record data set (RRDS) . If this operand is omitted, the 
address of the field which contains the record number is 
assumed to be in TCAFCRI. 

Notes ; 

1. The SRCHTYP operand is assumed to be FKEQ on all DFHFC 
macros except SETL and RSETL when only FKEQ and FKGE 
will be accepted* 

2. In skip sequential operation, if the relative record 
number refers to a non-existent or deleted record, the 
NOTFND condition will be raised, even if SETL or RESETL 
included SRCHTYP=FKGE. 

RETMETH= 

applies only to blocked DAM data sets and is used to specify 
the argument type (retrieval method) for deblocking the data 
sets. It is also used to specify the format of the information 
placed in the record information field each time a record is 
retrieved in a browse operation. It is invalid if INDEX is 
specified, because a blocked DAM data set cannot be an index 
data set for indirect accessing * 

RELREC 

specifies that retrieval is to occur by relative record, 
with the first record in a block considered to be record 
zero. It also specifies that a one— byte binary relative 
record number is provided in a browse operation. 



KEY 



specifies that retrieval is to occur by key or that in a 
browse operation, a key is to be provided. 



If TYPOPER=UPDATE is specified for a DAM data set, this operand 
is required* If this operand is omitted and a request to read 
a blocked DAM data set is issued, the entire physical record 
(block) is returned in the FIOA to the application program. 
The block reference field, required by DAM, contains the 
criteria for deblocking the data set. If a retrieved record is 
"undefined," the application program must determine the length 
of the record* 

SEGIDER=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the segment set specified by the 
SEGSET operand (at TCAFCSI) cannot be located for this data set 
in the FCT . SEGIDER signifies "segment set identification 
error." 

The field TCAFCAA contains: 

• Zero for GET, SETL, or RESETL 

• The address of the FWA for GETNEXT 

For RESETL, the browse operation will have been terminated. 
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SEGSET= 



SRCHTYP= 



indicates that the data set specified in the DATASET operand 
contains segmented records and identifies the segment set to be 
retrieved, or specifies a new default segment set name to be 
used in a browse operation. When used in a browse operation, 
it also indicates the default segment set to be retrieved if no 
segment set name is specified in a subsequent TYPE=GETNEXT 
macro. This segment set name is used as the default throughout 
the browse unless altered by a TYPE=RESETL macro. If locate 
mode is specified in a TYPE=SETL macro initiating a browse, 
SEGSET is invalid and including it will raise the invalid 
request (INVREQ) condition i 

symbolic name 

is the symbolic name of the segment set to be retrieved, or 
the symbolic name of the default segment set. The name 
must have been defined in t'ie associated segment control 
section of the FCT* 

YES 

indicates that the symbolic name of the segment set to be 
retrieved, or of the default segment set, has been placed 
in TCAFCSI* When used with a TYPE=POT macro it specifies 
that the data set contains segmented records* 

ALL 

indicates that the entire record in an unpacked and aligned 
format is required. SEGSET=ALL is assumed by CICS/VS when 
updating a segmented record no matter what is specified in 
the SEGSET operand; the entire record is unpacked and 
returned to the application program. 

If this operand is omitted, and the DFHFC TYPE=GET or TYPE=SETL 
macro instruction refers to a data set containing segmented 
records, the record is returned in its packed unaligned format. 
Also, if this operand is omitted, the segment set name 
specified in a preceding SETL or RESETL macro instruction for a 
browse operation continues to be the segment set name. 



specifies how the search key in the record identification field 
is to be used (VSAM records only) . This operand is meaningful 
only when ARGTYP=KEY is specified or implied by default! 

FKEQ 

indicates that the search key is a full key and that only a 
record with an equal key satisfies the search. When used 
with TYPE=DELETE, all records whose keys match the search 
key are deleted. 

FKGE 

indicates that the search key is a full key and that the 
first record with a key equal to or greater than the search 
key satisfies the search. 
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GKEQ 

indicates that the search key is a generic (partial) key, 
the binary length of which is specified in the first byte 
of the record identification field. A record whose key is 
equal to the search key (compared on only the number of 
bytes specified in the first byte of the record 
identification field) satisfies the search. When used with 
TYPE=DELETE, all records whose keys begin with the search 
key are to be deleted; A count of the number of records 
deleted is returned in TCAFCNRD. 

GKGE 

indicates that the search key is a generic key and that the 
first record with a key equal to or greater than the search 
key (compared on only the number of bytes specified in the 
first byte of the record identification field) satisfies 



the search. 
TYPOPER= 



describes the file operation to be performed. 

NEWREC 

indicates that a new record is to be added to an existing 
data set. 

UPDATE 

when used with a TYPE=PUT macro, it indicates that a record 
retrieved previously by a DFHFC TYPE=GET,TYPOPER=UPDATE 
instruction is to be updated (in effect, rewritten to the 
data set) . When used with a TYPE=GET macro, it indicates 
that a record is to be obtained for updating, or, if a VSAM 
key— sequenced data set is referred to, for either updating 
or deletion. If records in a protected VSAM key— sequenced 
data set are to be updated or deleted, ARGTYP=KEY must be 
specified and SRCHTYP must be FKEQ. If the record is from 
a blocked DAM data set, the RETMETH operand must be 
specified. If TYPOPER=UPDATE is omitted, a read-only 
operation is assumed. 

The UPDATE parameter can also be used with TYPE=PUT to 
write a record to a DAM data set after building the record 
in an area obtained by a DFHFC TYPE=GETAREA macro . This 
technique is described in detail in the section "DAM Data 
Sets" earlier in this chapter. 

DELETE 

is valid only when a VSAM key— sequenced data set is being 
accessed and indicates that a record previously retrieved 
for update by a DFHFC TYPE=GET,TYPOPER=UPDATE request is to 
be deleted from the data set * 

MASSINSERT 

is applicable only to VSAM data sets and specifies that the 
acquired FWA is to be used for a mass— insert operation. 
This ensures that the same FWA is used for subsequent DFHFC 
TYPE=PUT macro instructions adding new logical records with 
keys or relative byte addresses in ascending sequence to 
the data set. The FWA is made available to the application 
program after each DFHFC TYPE=PUT macro instruction* The 
FWA is reinitialized, before each return to the application 
program, to the value specified in the INITIMG operand (if 
specified) or otherwise to EBCDIC blanks (X^UO 1 ) . A mass- 
insert operation is terminated by a DFHFC TYPE=RELEASE 
macro instruction. 
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Chapter 3.3. DL/I Services 



The CICS/VS application programmer can request Data Language/I (DL/I) 
services in two ways: 

1. By issuing a DL/I CALL statement, written according to DL/I 
specifications. This method is available to both CICS/OS/VS and 
CICS/DOS/VS users. This DL/I CALL is mandatory if the user wishes 
to access remote DL/I data bases using ISC. 

2. By issuing a DFHFC macro instruction* This method is available to 
CICS/OS/VS users only. 

In both cases, control is passed to a routine that acts as an 
interface between the CICS/VS application program and the DL/I request 
handler. This routine performs validity checks on the CALL list, 
prepares DL/I to handle the request, and passes control and the CALL 
list to DL/I. After DL/I has handled the request, it returns control to 
the calling program unless a DL/I pseudo-abend has occurred, in which 
case the CICS/VS task is abnormally terminated. 

Under CICS/VS, two or more transactions (tasks) may require the same 
application program at any given time during system operation. Because 
CICS/VS application programs must be quasi— reenterable (see "Quasi— 
Reenterability," in Chapter 1.1), DL/I areas that may be modified under 
CICS/OS/VS (such as PCB pointers, I/O work areas, and segment search 
arguments) should not be placed in static storage* They should also not 
be placed in working storage (unless the application program contains 
one or more command— level statements, in which case working storage is 
dynamic) . Storage for such areas must be obtained from CICS/VS dynamic 
storage by each transaction using the program. 

Pour steps must be performed by an application program requesting 
DL/I data base services. These steps are listed below and explained in 
the sections that follow. 

1. Obtain addresses of program communication blocks (PCBs) to be used 
by the application program. 

2. Building segment search arguments (SSAs) if they are to be used in 
the CALL. 

3. Acquire I/O work areas for DL/I segments processed by the program. 

4. Issue the DL/I CALL. 



Obtaining Addresses of Program Communication Blocks 

An application program that uses the CICS/VS— DL/I interface accesses 
data bases by means of program communication blocks (PCBs) . One PCB for 
each data base is included in the program specification block (PSB) for 
the program. To process DL/I CALLs within a CICS/VS transaction, the 
PSB for the transaction must be scheduled and the PCB addresses obtained 
before any DL/I CALLs are made. Scheduling involves, for example, that 
all the required DL/I control blocks exist and are in main storage, and 
that the processing options associated with this PSB permit it to be 
scheduled concurrently with those PSBs already scheduled. If they are 
not obtained, an INVREQ (invalid request) indicator is returned in 
response to any DL/I CALL within the program. 

Chapter 3.3. DL/I Services 135 



A transaction may schedule only one PSB at a time. An attempt to 
schedule a second PSB while one is still scheduled causes the INVREQ 
indicator to be returned. 

A sync point request (refer to the DFHSP macro instruction in Chapter 
7.5) by a task that is scheduled to use DL/I resources implies the 
release of those resources. This means that if, after issuing a DFHSP 
TYPE=USER macro instruction, access to a DL/I data base is required, the 
desired PSB must be rescheduled* The previous position of that data 
base has been lost. 

| I/O PCBs (a type of control block used by IHS/VS) are not passed to 
I CICS/VS programs, even though they may be included in a transaction's 
| PSB, either explicitly or implicitly by means of the COMPAT=YES option. 



DFHPC MACRO INSTRUCTION (CICS/OS/VS ONLY) 



To schedule the desired PSB and obtain PCB addresses, the CICS/OS/VS 
application programmer may use a special form of the DFHFC macro 
instruction: 




TYPE= (DL/I, PCB) 

[ ,PSB={ , psbname» |symbolic address|YES} ] 

[ ,NORESP=symbolic address] 

[ ,DLINA=symbolic address] 

[ ,PSBSCH=symbolic address] 

[ ,PSBNF=symbolic address] 

[ ,PSBFAIL=symbolic address] 

[ ,INVREQ=symbolic address] 



where: 

TYPE= (DL/I, PCB) 

indicates that PCB addresses are to be acquired * 

Note : DL/I in the TYPE= operand may also be coded as DLI or 
DLL 

If the PSB has been located, TCADLPCB contains the address of a list 
of PCB addresses in the sequence in which the PCB addresses were 
specified during the PSBGEN of this PSB* If the PSB cannot be found, 
TCADLPCB contains zero. If the PSB pool or DMB pool is too small to 
hold the requested blocks even when no other PSBs or DMBs are in their 
pools, the transaction is terminated with the ADLA ABEND code. 
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DL/I CALL STATEMENT (CICS/DOS/VS OR CICS/OS/VS) 

Upon receiving control from CICS/VS, a CICS/VS application program must 
issue a DL/I call to perform scheduling before attempting to access DL/I 
data bases. If the scheduling call is successful, the address of the 
PCB list is returned in the field TCADLPCB and TCAFCTR is set to zeros. 
If the call is unsuccessful, TCADLPCB contains zeros and TCAFCTR 
contains a one— byte return code* Before continuing with subsequent DL/I 
calls, it is the application programmers responsibility to test these 
indicators to determine whether scheduling was successful. 

The format of the CALL statement to request scheduling is as follows: 

For Assembler language ; 

CALLDLI {ASMTDLI|CBLTDLI} , ([ parmcount , ]f unction, [psb]) 

For COBOL ; 

CALL •CBLTDLI 1 USING [ parmcount, ]function,[ psb ]. 

For PL/I ; 

CALL PLITDLI ([ parmcount , ]f unction, [ psb ]) ; 

where; 

parmcount 

is the name of a binary fullword containing the parameter count 
(value of one or two) . This parameter is optional. 



function 



psb 



is the name of the field containing the four-character function 
»PCB#». 

is the name of the eight— byte field containing the PSB 
generation name which the application program accesses. (This 
name is one to eight bytes long under CICS/OS/VS, or one to 
seven bytes long under CICS/DOS/VS, and is left justified and 
padded on the right with blanks as appropriate.) This parameter 
is optional. Under CICS/DOS/VS if it is omitted, the PSB name 
is assumed to be the first PSB name associated with the 
application program name in the DL/I application control table 
generation. Under CICS/OS/VS if it is omitted, the PSB name is 
assumed to be the name of the application program associated 
with the task in the PCT* 



Building Segment Search Arguments 

Both CICS/OS/VS and CICS/DOS/VS application programmers can use segment 
search arguments (SSAs) in a DL/I CALL to identify a specific segment, 
or, if qualified, to identify the range of values within which a segment 
exists. In addition, the CICS/OS/VS programmer can specify SSAs in a 
DFHFC TIPE=DL/I macro instruction* If used, SSAs must be built by the 
application programmer before a DL/I CALL is issued. (For information 
concerning how to build an SSA, CICS/OS/VS application programmers 
should refer to the IMS/VS Application Programming Reference Manual ; 



Chapter 3.3. DL/I Services 137 



CICS/DOS/VS users should refer to the DL/I DOS/YS Application 
P rogramming Reference Manual * ) 

In a DL/I application program, SSAs are built in fixed storage within 
the program. In a CICS/VS application program, SSAs must be built in 
dynamic storage to maintain the quasi— reenterability of the program. 

The storage acquired to build the SSAs is addressed as follows: 

• For Assembler— language programs, the address should be placed in 
the register that establishes addressability for the SSA dynamic 
storage. 

• For COBOL programs, the address is moved to the BLL pointer for 
this storage. The BLL pointer is defined under the COPY DFHBLLDS 
statement in the Linkage Section and must be in the same relative 
position in the BLL list as the 01 statement for the SSA dynamic 
storage is among the 01 statements in the Linkage Section; 

• - For PL/I, the address is stored in the variable upon which the SSA 

dynamic storage is based. 

After the storage has been acquired and the SSAs built, DL/I CALLs in 
which the SSAs are used can be issued by the application program* The 
names of the SSAs to be used, if any, are specified in the parameter 
list of the CALL. Under CICS/OS/VS, a DFHFC TYPE=DL/I macro instruction 
can also be used* In a DFHFC TYPE=DL/I macro instruction, the 
application programmer can specify the number and names of the SSAs in 
different ways: 

1. SSAS=NO indicates that there are no SSAs in this CALL. 

2* SSAS= (ssacount,ssa1,ssa2, * * .) , where ssa count is optional, 

represents either the fixed— point number of SSAs in the CALL or the 
symbolic address of the fullword that contains the number of SSAs. 
Specifying a field to contain the number of SSAs provides the 
application programmer with flexibility in writing one DFHFC 
statement to be used in many different CALLs* ssal, ssa2 , . . . , are 
the symbolic names of the SSAs* 

3. SSALIST=YES indicates that the application programmer has built a 
list of fullwords, optionally containing the number of SSAs (which 
may be zero) in the first word, and the addresses of the SSAs in 
the following words, and that he has stored the address of this 
list at TCADLSSA* 

4. SSALIST=symbolic address indicates that the address of an SSA list 
built by the application programmer as indicated in item 3 is at 
the location specified* 

In Assembler— language programs, ssacount,ssa1,ssa2, . . . , can be 
contained in registers if the specifications are enclosed in 
parentheses! 



Acquiring an I/O Work Area 

When issuing a request for DL/I services, the address of a work area, 
either that in which a current segment is contained or that in which 
DL/I is to place the segment in a retrieval CALL, is required. This 
area must be specified by the CICS/OS/VS or CICS/DOS/VS programmer who 
issues a DL/I CALL. It may be provided by the interface, if the 
programmer desires, for a retrieval— type DFHFC macro instruction. 
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If the CICS/OS/VS application programmer knows the address of the 
work area to be used in the DFHFC macro instruction, including the case 
for which storage is acquired for a retrieval— type (Gxxx) request, he 
specifies the name of the pointer to that storage in the WRKAREA=name 
operand, or he places the address of the storage in TCADLIO before 
issuing the request and specifies WRKAREA=YES. 

If the application programmer wishes to allow the interface to obtain 
the work area for a retrieval— type reguest, he does not include the 
WRKAHEA operand in the DFHFC macro request. If the request was serviced 
successfully, the address of an acquired I/O work area is in TCADLIO. 
The address at TCADLIO is the address of the storage accounting area 
(SAA) preceding the retrieved data. The area becomes the responsibility 
of the programmer and is not freed until he frees it or until the 
transaction terminates. If the application programmer elects to free 
the work area, he must use a DFHSC TYPE=FREEMAIN macro instruction. 

Note : The address of the I/O area is specified as the address of the 
storage accounting area preceding the data when a DFHFC macro 
instruction is used; the address of the first byte of the data area is 
required when a DL/I CALL is used. 



I Requesting DL/I Services 

The application program request for DL/I services may be either a 
CICS/VS DFHFC macro instruction (CICS/OS/VS) or a DL/I call (CICS/OS/VS 
or CICS/DOS/VS) . 



DFHFC MACRO INSTRUCTION (CICS/OS/VS) 



The format of the DFHFC macro instruction to request that a particular 
DL/I function be performed is as follows: 



TYPE=(DL/I [, function]) 

[ ,PCB= {symbolic address| (register)}] 

[ ,HRKAREA= {symbolic address)YES| (register)} ] 

[ , SSAS={NO| ([ssacount][ ,ssa1][ ,ssa2, . . . ]) | 

(C (register!) ][ , (register2) ,..*])}] 
[ ,SSALIST= {YES | NO | symbolic address| (register)}] 
[ ,NORESP=symbolic address] 
[ ,NOTOPEN=symbolic address] 
[ ,DLINA=symbolic address] 
[ ,FDNCNS=symbolic address] 
[ ,INVREQ=symbolic address] 




where: 

TYPE=(DL/I [, function]) 

specifies the two— to four— byte name of the function to be 
performed. If the function is not specified, it is assumed to 
be in TCADLFUN. 



Note : 
DL1* 



DL/I in the TYPE= operand may also be coded as DLI or 
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DL/I CALL STATEMENT (CICS/OS/VS OR CICS/DOS/VS ) 

DL/I data base services are available to CICS/VS application programs 
| through CALL statements. The CALL statement formats for COBOL and PL /I 
are similar* For Assembler— language application programs, a CALLDLI 
macro instruction is used. The formats of the DL/I calls are as 
follows: 

For Assembler language : 

CALLDLI {ASMTDLI| CBLTDLI} [ , ([ parmcount, ]f unction ,pcb,workarea[ ,ssa, ... ]) ] 

For COBOL : 

CALL ■CBLTDLI 1 USING [ parmcount, ]function,pcb, workarea[ ,ssa, ... ]. 

For PL/I : 

CALL PLITDLI (parmcount , function, pcb,workarea[ ,ssa, . . . ]) ; 

where: 

parmcount 

is the name of a binary fullword containing the parameter count 
or argument count of the arguments which follow; this is 
optional for Assembler language and COBOL. 

function 

is the name of the field containing the four— character DL/I 
input/output CALL function desired* 

pcb 

is the program communication block (PCB) name (or DSECT name if 
Assembler) • 

workarea 

is the name of the I/O work area* 

ssal to ssan 

are the names of the segment search arguments (SSAs) ; these are 
optional. 

Notes : 

1. If no parameters are specified in an Assembler— language CALLDLI 
macro instruction, register 1 is assumed to contain the address of 
a parameter list. 

2. In Assembler language, an alternative format may be used: 

CALLDLI {ASMTDLI | CBLTDLI}, HF=(E, (register) or address) 

where: 

address 

is the address of the parameter list, or register that contains 
the address of the parameter list. 
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Releasing a PSB in the CICS/VS Application Program 

To reduce pool and intent contention, the CICS/OS/VS application program 
can release the PSB after a DL/I service has been requested. 

It is recommended that conversational programs release the PSB before 
writing to a terminal so that other transactions can use the PSB while 
the conversational program is waiting for an operator response. 

To ensure data-base integrity, a request to release a PSB other than 
a read— only PSB implies the end of a logical unit of work for the entire 
task. This means that a DFHSP TYPB=USER is issued on behalf of a task 
that is releasing a PSB, unless the PSB is read— only and is resident on 
the system that issued the call. 



DFHFC MACRO INSTRUCTION (CICS/OS/VS ONLY) 



To release a PSB for use by other transactions, the CICS/OS/VS 
application programmer may issue a macro instruction of the following 
format: 




DFHFC | TYPE= (DL/I, {TERM |T}) 

| [ ,DLINA=symbolic address] 

| [ ,TERMNS=symbolic address] 

| [ ,INVREQ=symbolic address] 



where: 

TYPE= (DL/I, TERM) 

specifies that the PSB is to be released for use by other 
transactions, or, if not required, its pool space and 
associated DMB pool space may be released for other purposes. 

Note s: 

1. DL/I in the TYPE= operand may also be coded as DLI or DLL 

2. TERM may be abbreviated as Ti 

Before issuing any other DL/I CALLs or DFHFC macro instructions 
reguesting DL/I access to a data base, the application programmer must 
again issue a schedule request. All positioning in data bases referred 
to by the transaction is lost when the PSB is released. Thus, if the 
program was processing a hierarchy through GNxx requests before 
releasing the PSB, it is necessary to explicitly reposition the data 
bases after issuing another schedule request, to continue the GNxx 
requests. 



DL/I CALL STATEMENT (CICS/DOS/VS OR CICS/OS/VS) 

If the CICS/VS application program desires to relinquish control of the 
PSB, it must issue a terminal call to DL/I. The format of the CALL 
statement to reguest termination is as follows: 
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For Assembler language: 

CALLDLI {ASHTDLI ICBLTDLI} , ([parmcount, ]f unction) 

For COBOL; 

CALL ■CBLTDLI* USING [ parmcount, ]function . 
For PL/I ; 

CALL PLITDLI ([ parmcount , ]f unction) ; 

where: 

parmcount 

is the name of a binary fullword containing the parameter count 
value of one. 

function 

is the name of the field containing the four-character function 
•TERM* or 'TJpJT* * 

When a termination call is issued for a previously scheduled PSB, the 
resources acquired for the task are released, and tasks awaiting the 
resources are given an opportunity to be scheduled. 



I DL/I Services Response Codes 

I To test a response code, the application programmer must know the 

CICS/VS response codes and their meanings. If the Assembler— language or 
PL/I programmer elects to use this approach, he can access the response 
codes for NORESP, INVREQ, and NOTOPEN at TCAFCTR; the response codes for 
all other conditions can be accessed at TCADLTR. The COBOL programmer 
can access the response codes for NORESP, INVREQ, and NOTOPEN at 
TCAFCRC; the response codes for all other conditions can be accessed at 
TCADLTR. The possible response codes and the conditions to which they 
correspond are identified in the right— hand column of Figure 3.3—1. 
CICS/VS-DL/I interface reguests for which the conditions are applicable 
are shown at the left. 
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r 


uest | 


Condition | 




Response Code 


| 


j DL/I Interface Req 


Assembler | COBOL | 


PL/I | 


| (DL/I, PCB) , (DL/I 
| [ ,£ unction]) , CHECK 




NORESP 
(Normal | 
Response) j 


X«00» | 


LOW-VALUES ! 
(FCNORESP) | 


00000000 | 


| (DL/I[ ,f unction ]) , 
| CHECK 




NOTOPEN | 
(Not open) 


X«0C» | 


12-4-8-9 | 
(FCNOTOPEN) 


00001100 | 


I All 




INVREQ | 
(Invalid 

Request) | 

• 


X'OB 1 


12-8-9 | 
(FCINVREQ) | 

• 


00001000 | 


| Codes 


returned in TCADLTR after NOTOPEN condition | 


I (DL/I[ function]) , 
I CHECK 




Data base 
not open; | 
request 
issued in 

OS/VS | 
system 


X»00» 


LOW-VALUES 


00000000 | 






Data base | 
not open; 
request 
issued in 
DOS/VS 
system 


X«01» 


12-1-9 | 


00000001 | 






Intent 
scheduling 

conflict 

■ 


X»02« 


12-2-9 

• 


00000010 | 


I Codes 


retui 


:ned in TCADLQ 


?R after INVREQ condition | 


I ALL 




D/Base not 
in FCT, or 
D/Base not 
open ace— 

| ording to 
FCT, or in- 
valid argu— 

1 ment passed 
to DL/I 


x»oo» 


| LOW-VALUES 


00000000 | 


| (DL/I, PCB) , CHECK 




I PSBNF 

| (PSB Not 

I Found) 


I X«01» 


I 12-1-9 
| (DLPSBNF) 


I 00000001 | 


| CHECK 




| TASKNA 

| (Task Not 

| Authorized) 


| X«02» 


| 12-2-9 

| (DLTASKNA) 


| 00000010 | 


| (DL/I, PCB) , CHECK 




I PSBSCH 
| (PSB Al- 
| ready Sche— 
| duled 


| X«03« 


| 12-3-9 

| (DLPSBSCH) 


| 00000011 | 



Figure 3*3—1. (Part 1 of 2) CICS/VS— DL/I Interface Response Codes 
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1 


Condition 


• 

Response Code | 


1 DL/I Interface Request 


i 
Assembler 


i i 

COBOL | PL/I | 


| CHECK 


LANGCON 

(Language 

Conflict) 


X»04« | 


12-4-9 | 00000100 | 
(DLLANGCON) | | 


| (DL/I,PCB) , CHECK 


PSBFAIL 
(PSB Ini- 
tialization 
Failed) 


X»05» 


12-5-9 | 00000101 | 
(DLPSBFAIL) | | 


| CHECK 


PSBNA 
(PSB Not 
Authorized) 


X«06» 


12-6-9 | 00000110 | 
(DLPSBNA) | | 


| (DL/I ,T), CHECK 


TERMNS 
(Termina- 
tion Not 
Scheduled) 


X»07« 


12-7-9 | 00000111 | 
(DLTERMNS) | | 


| (DL/I[ ,f unction]) , 
| CHECK 


FUNCNS 
(Function 
Not Sche- 
duled) 


X»08» 


| 12-8-9 | 00001000 | 
(DLFUNCNS) | | 


1 Any DL/I access CALL 
| (except TERM and PCB) 
| on a remote system 


Invalid PCB 
adddress 


XMO" 


12-11-1-8-9| 00010000 | 


| All 


I DLINA 
(DL/I Not 
Active) 


| X»FF« 


HIGH-VALUES | 11111111 | 
(DLINA) | | 


1 Notes: 








I 1* The TASKNA and LANGCON conditions apply only to CICS/DOS/VS. | 


| 2. PSBNA occurs only 


when the date 


i base is on a DOS/VS system* | 


| 3. The names enclosec 
| indicate the cond: 
I names may be used 
| in a COBOL prograi 


I in parentheses in the COBOL column | 

Ltion names generated by CICS/VS* These | 

in testing for the respective conditions | 

a. | 



Figure 3.3—1* (Part 2 of 2) CICS/VS— DL/I Interface Response Codes 
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I Test Response to a DL/I Request (TYPE=CHECK) 



I The format of the DFHFC macro instruction to test the CICS/VS response 
| to a preceding DL/I request is as follows: 




TIPE=CHECK 

[ ,NORESP=symbolic address] 
[ ,DLINA=symbolic address] 
[ ,PSBSCH=symbolic address] 
[ ,PSBNF=symbolic address] 
[ ,PSBFAIL=symbolic address] 
[ ,FUNCNS=symbolic address] 
[ ,TERMNS=symbolic address] 
[ ,LANGCON=symbolic address] 
[ ,TASKNA=symbolic address] 
[ / PSBNA=symbolic address] 
[ ,INVREQ=symbolic address] 
[ ,NOTOPEN=symbolic address] 



CICS/DOS/VS only 
CICS/DOS/VS only 
CICS/DOS/VS only 



where: 

TYPE=CHECK 

indicates that the CICS/VS— DL/I interface response is to be 
checked . 

The application programmer may use the DFHFC TYPE=CHECK macro 
instruction following a DL/I CALL statement or a DFHFC 
TYPE= (DL/I[,f unction]) macro instruction. This macro instruction does 
not check the DL/I return codes in the PCB. If DL/I issues a pseudo- 
abend during processing of the request, control is not returned to the 
application programs The transaction is terminated with CICS/VS abend 
code ADLA. For CICS/DOS/VS, if DL/I issues a pseudo-abend during a 
call, the transaction is terminated with a Dnnn abend code where nnn is 
the DL/I pseudo— abend code. 

If the application programmer does not provide for the checking of a 
particular response, and if the exception condition corresponding to 
that response occurs, program flow proceeds to the instruction following 
the DL/I request in the application program. 
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DL/I Requests in an Assembler-language Program (CICS/OS/VS) 

The application programmer must first get the addresses of the PCB. 
When CICS/OS/VS returns from servicing the PCB request, if the 
programmer loads register 1 from TCADLPCB, his program is in the same 
state as after an ENTRY DLITCBL statement has been executed in an IMS/VS 
DL/I application program. 

The examples that follow show the options available to the 
application programmer in a few of the acceptable combinations. The 
application program must be quasi— reenterable. If a DFHFC macro 
instruction is issued, the PCB and WRKAREA operands are used to specify 
the addresses of pointers to fields rather than the addresses of fields 
desired* 



* 


COPY 


DFHTCADS 


PSBNAME 


DC 


CL8' 


•PSBNAME* 


PCBFUN 


DC 


CL4 


•PCBb» 


PCBPTRS 

* 


DSECT 




PCB1PTR 


DS 


F 




PCB2PTR 


DS 


F 




• 

WORKAPTR DS 


F 




PCB1 


DSECT 





COPY TCA DEFINITION - INCLUDES 

DL/I FIELDS 

NAME OF PSB TO BE USED 

PCB FUNCTION 

PCB POINTERS RETURNED BY 

INTERFACE 

STORAGE FOR PCB POINTERS 



STORAGE FOR POINTER IN I/O WORK 

AREA 

PCB DSECT 



PCB2 



DSECT 



PCB DSECT 



WRKAREA 


DSECT 




DS 2F 


WORKA1 


DS CL40 


SSAREA 


DSECT 




DS 2F 


SSA1 


DS CL40 


SSA2 


DS CL20 



DL/I WORK AREA DSECT 
STORAGE PREFIX 
WORK AREA 
SSA DSECT 
STORAGE PREFIX 
SSA1 LAYOUT 
SSA2 LAYOUT 



DFHFC TYPE= (DL/I, PCB) 
DFHFC TYPE= (DL/I, PCB) , 

PSB=»PSB14 I 
DFHFC TYPE= (DL/I, PCB), 

PSB=PSBNAME 
MVC TCADLPSB,=CL8«PSBA» 
DFHFC TYPE= (DL/I, PCB) , 

PSB=YES 
L R1, TCADLPCB 

USING PCBPTRS, R1 



* 
* 

* ISSUE A PCB REQUEST VIA CALLDLI 

CALLDLI CBLTDLI, (PCBFUN) 
CALLDLI CBLTDLI, (PCBFUN, PSBNAME) 
L R1, TCADLPCB 

* ACQUIRE STORAGE FOR WORK AREA 



USE PSB FOR THIS PROGRAM 

GET PCB'S IN •PSB14» * 

GET PCB'S IN SPECIFIED PSB * 

PUT PSB NAME IN TCA 

GET PCB'S OF PSB NAMED IN TCA i 

GET ADDRESS OF PCB ADDR LIST 

REG 1 IS BASE OF PCB POINTERS 

USER MUST PROVIDE ADDRESSABILITY 
TO PCB'S WHEN USING THEM 

USE PSB FOR THIS PROGRAM 

GBT PCB»S IN SPECIFIED PSB 

GET ADDRESS OF PCB ADDRESS LIST 
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DFHSC TYPE=GETMAIN / ... 
L R2,TCASCSA 
USING HRKAREA,R2 
ACQUIRE STORAGE FOR SSA»S 

DFHSC TYPE=GETMAIN,.*. 
L R3,TCASCSA 
USING SSAREA,R3 



GET STORAGE FOR WORK AREA 
REG 2 IS BASE FOR WORK AREA 
TELL ASSEMBLER 

GET STORAGE FOR SSA'S 
REG 3 IS BASE FOR SSA'S 
INDICATE TO ASSEMBLER 



CALLDLI CBLTDLI, (function, PCB 1,WORKA1 ,SSA 1 ,SSA2 ) 
CALL DL/I VIA DFHFC MACRO — VARIOUS EXAMPLES 
EXAMPLE 1 



DFHFC TYPE= (DL/I, f unction) , 
PCB=PCB1PTR, 
WRKAREA=WORKAPTR, 
SSAS=(2,SSA1,SSA2) , 
NORESP=GOOD1 



EXAMPLE 2 



MVC TCADLPCB,PCB1PTR 
LA RO,WRKAREA 
ST R0,TCADLIO 
DFHFC TYPE= (DL/I,DLET) , 

WRKAREA=YES, 

SSAS=NO 



EXAMPLE 3 



MVC TCADLFUN,=CL4 , GU» 
DFHSC TYPE=GETMAIN,... 



L 


R4,TCASCSA 


LA 


R4,8(R4) 


LA 


R0,1 


ST 


R0,0(R4) 


LA 


R0,SSA1 


ST 


R0,4 (R4) 


ST 


R4,TCADLSSA 


01 


4 (R4) jX'SO 1 


DFHFC 


TYPE=DL/I, 




PCB=PCB1PTR, 




SSALIST=YES 


L 


R3,TCADLI0 



PCB IS POINTED TO 

WORK AREA IS POINTED TO 

SSA COUNT AND SSAS SPECIFIED 

NORMAL RESPONSE BRANCH 



PRELOAD PCB POINTER 

PICK UP WORK AREA ADDRESS 

STORE IN TCA 

FUNCTION SPECIFIED 

WORK AREA ADDRESS PRELOADED 

NO SSAS 



PRELOAD FUNCTION 

GET STORAGE FOR SSA LIST 

PICK UP STORAGE ADDRESS 

BYPASS PREFIX 

GET COUNT OF SSA»S 

STORE IN SSA LIST 

GET ADDRESS OF •SSAI* 

STORE IN SSA LIST 

STORE LIST ADDRESS IN TCA 

SET ON THE END-OF-LIST BIT 

DL/I CALL, FUNCTION PRELOADED * 

POINTER TO PCB TO BE USED * 

INTERFACE WILL PROVIDE WORK AREA* 

PROBLEM PGM PROVIDES SSA LIST 

PICK UP ADDRESS OF SUPPLIED 

WORK AREA 
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DL/I Requests in a COBOL Program (CICS/OS/VS) 

Upon program entry , the COBOL programmer should obtain PCB addresses by 
issuing a DFHFC TYPB= (DL/I, PCB) request or a DL/I 'PCB 1 call J After 
CICS/OS/VS returns control, the programmer moves the contents of 
TcADLPCB to the BLL pointer which is the base for the layout of the PCB 
pointers in the Linkage Section. He then moves the addresses of the 
PCBs to their BLL pointers to provide the base addresses for the PCBs. 
When this is done, the program is in the same state as after an ENTRY 
•DLITCBL 1 USING PCB1,PCB2 statement has been executed in an IMS/VS DL/I 
application program. 

Por an explanation of how BLL pointers to 01 statements in the 
Linkage Section are defined, see the discussion of COBOL application 
programming in Chapter 2.3* 

Examples showing how to write DL/I requests are given below. Only 
some combinations of operands are shown, but other combinations are 
acceptable* Note that, in a DFHFC request, BLL pointers to the PCB and 
work area are used rather than actual field names * This is the only way 
the addresses can be passed to DL/I* 



WORKING-STORAGE SECTION. 
77 PSBNAME PIC X (8 ) VALUE 'PSBNAME*. 
77 PCB-FUNCTION PIC X (4) VALUE 'PCB^* 
77 FUNCTION-1 PIC X (4) VALUE •DLET». 
77 SSA-COUNT PIC S9 (8) COMP VALUE 2. 
LINKAGE SECTION. 
01 DFHBLLDS COPY DFHBLLDS 
02 ... 



01 
01 



NOTE POINTERS TO OTHER CICS/VS 
AREAS NEEDED 



02 B-PCB-PTRS PIC S9 (8) COMP. 
02 B-PCB1 PIC S9(8) COMP. 
02 B-PCB2 PIC S9 (8) COMP. 
02 B-WORKAREA PIC S9(8) COMP. 
02 B-SSAS PIC S9 (8) COMP. 
DFHCSADS COPY DFHCSADS. 
DFHTCADS COPY DFHTCADS. 



NOTE TWO DEFINITIONS. 

NOTE OTHER AREA DEFINITIONS. 



01 PCB-PTRS. 

02 PCB1-PTR PIC S9 (8) COMP. 

02 PCB2-PTR PIC S9(8) COMP* 
01 PCB1. 



01 PCB2 



01 WORKAREA. 

02 FILLER PIC X (8) . 
02 WORKA1 PIC X(40) 



NOTE STORAGE PREFIX 



01 SSAREA. 

02 FILLER PIC X (8) . 
02 SSA1 PIC X (40) . 
02 SSA2 PIC X (60) * 
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PROCEDURE DIVISION. 

* GET PCB ADDRESSES 

DFHFC TYPE=(DL/I,PCB) GET PSB FOR THIS PROGRAM 

* GET PCB ADDRESSES VIA CALL 

CALL •CBLTDLI" USING PCB-FUNCTION ,PSBNAME* 

NOTE GET PCB'S FOR SPECIFIED PSB* 

* SAVE PCB ADDRESSES IN BLL TABLE SO PCB ■ S CAN BE ADDRESSED 

MOVE TCADLPCB TO B-PCB-PTRS. 
MOVE PCB1-PTR TO B-PCB1 . 
MOVE PCB2-PTR TO B-PCB2. 

* OPTIONALLY, ACQUIRE STORAGE FOR WORK AREA 

DFHSC TYPE=GBTMAIN,. . . 
MOVE TCASCSA TO B-WORKAREA. 

* OPTIONALLY, ACQUIRE STORAGE FOR SEGMENT SEARCH ARGUMENTS 

DFHSC TYPE=GETMAIN,. *. 
MOVE TCASCSA TO B-SSAS. 

* CALL DL/I VIA CALL 

CALL »CBLTDLI« USING FUNCTION-1 ,PCB1 ,WORKA1 ,SSA 1 ,SSA2. 

* EXAMPLE 1 OF DFHFC MACRO INSTRUCTION 

DFHFC TYPE=(DL/I,GHU), FUNCTION * 

PCB=B-PCB1, PCB POINTER * 

WRKflREA=B-WORKAREA, WORK AREA POINTER * 

SSAS= (SSA-COUNT,SSA1,SSA2) SSA COUNT AND NAMES 

* EXAMPLE 2 OF DFHFC MACRO INSTRUCTION 

MOVE »GNP • TO TCADLFUN. NOTE PRELOAD FUNCTION. 

MOVE B-PCB1 TO TCADLPCB. NOTE PRELOAD PCB ADDRESS. 

DFHFC TYPE=DL/I, FUNCTION PRELOADED * 

SSAS=NO PCB ADDRESS PRELOADED * 

WORK AREA TO BE ACQUIRED * 

NO SSA'S 
MOVE TCADLIO to B-WORKAREA. NOTE SAVE ACQUIRED WORK AREA ADDR. 
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DL/I Requests in a PL/I Program (CICS/OS/VS) 

Upon entry to his program, the PL/I application programmer should get 
PCB addresses through a DFHFC TYPE= (DL/I ,PCB) statement or a DL/I •PCB 1 
call. When CICS/7S returns, the base address of a structure of PCB 
pointers is in TCADLPCB. The PL/I programmer must move the value from 
TCADLPCB to the based variable for his declared structure of PCB 
pointers. He then loads the pointers to all PCBs from this structurei 
When this has been done, the program is in the same state as an IMS/VS 
DL/I application program in which the 

DLITPLI: PROCEDURE (pcbnamel , 1 i .) OPTIONS (REENTRANT, MA IN ); 

statement has been executed* 

The PL/I programmer may then make DL/I reguests, either through CALLs 
or DL/I DFHFC macro instructions. Note that the PCB and WRKAREA 
operands in a DFHFC request specify the addresses of pointers to fields 
rather than of the fields desired i 



^INCLUDE DFHCSADS; 
^INCLUDE DFHTCADS; 



/* CSA DEFINITION */ 
/* TCA DEFINITION - INCLUDES */ 
/* DL/I FIELDS */ 
1 PCB_POINTERS BASED (B_PCB_PTRS) , 
2 PCB1_PTR POINTER, 



2 PCB2_PTR POINTER; 



DECLARE 1 PCB1 BASED (BPCB1) , 
2 ... 



/* PCB DEFINITIONS */ 



DECLARE 1 PCB2 BASED (BPCB2 ) , 
2 ... 

^ • • • f 

DECLARE 1 DLI_IOAREA BASED (BDLIIO) , /* DL/I I/O AREA */ 
2 STORAGE_PREFIX CHAR (8), 
2 IOKEY CHAR (6) , 
2 * . . f 
DECLARE 1 DLI_SSADS BASED (BSSADS), /* DL/I SSA LIST */ 
2 STORAGE_PREFIX CHAR (8) , 
2 SSA1, 

3 SSA1KEY CHAR (6) , 
3 ... 



(■PSBNAME*); 
INIT (»PCB •); 



GET PSB FOR THIS PROGRAM 



2 SSA2, 

3 j . . ; 

DECLARE PSBNAME CHAR (8) INIT 
DECLARE PCB_FUNCTION CHAR (8) 
/* OBTAIN PCB POINTERS */ 
DFHFC TYPE= (DL/I, PCB) 
/* OBTAIN PCB POINTERS VIA CALL */ 

CALL PLITDLI (PARM_CT,PCB_FUNCTION , PSBNAME) : /* GET SPECIFIED PSB */ 
/* SAVE POINTERS IN PCB BASES */ 
B_PCB_PTRS=TCADLPCB; 
BPCB1=PCB1_PTR; 
BPCB2=PCB2_PTR; 
/* ACQUIRE STORAGE FOR DL/I I/O AREA */ 
DFHSC TYPE=GETMAIN,CLASS=USER,..* 
BDLIIO=TCASCSA; 
/* OPTIONALLY, ACQUIRE STORAGE IN WHICH TO BUILD SSA»S */ 
DFHSC TYPE=GETMAIN ,CLASS=USER , . . . 
BSSADS=TCASCSA; 
/* OPTIONALLY , BUILD SEGMENT SEARCH ARGUMENTS */ 
SSA1KEY=TERMKEY; 
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/* CALL DL/I */ 

CALL PLITDLI (PARM_CT,DLI_FUNCTION ,PCB1 , IOKEY,SSA 1, 
SSA2) ; 
/* EXAMPLE 1 OF DFHFC MACRO INSTRUCTION */ 

DFHFC TYPE= (DL/I,ISRT), * 

PCB=BPCB1, PCB POINTER * 

WRKAREA=BDLIIO, WORK AREA POINTER * 

SSAS=(2,SSA1,SSA2) SSA COUNT AND NAMES 

/* EXAMPLE 2 OF DFHFC MACRO INSTRUCTION */ 
TCADLPCB=BPCB1 ; 

DFHFC TYPE=(DL/I,GU) , PCB PRELOADED * 

SSAS= (SSA_C0UNT,SSA1,SSA2) WORK AREA TO BE ACQUIRED * 

SSA COUNT AND NAMES 
BDLIIO=TCADLIO; /* SAVE WORK AREA ADDRESS */ 

/* EXAMPLE 3 OF DFHFC MACRO INSTRUCTION */ 

TCADLFUN=»GN i ; /* PRELOAD FUNCTION */ 

TCADLIO=BDLIIO; /* PRELOAD WORK AREA ADDRESS */ 

DFHFC TYPE=DL/I, FUNCTION PRELOADED * 

PCB=BPCB1, PCB POINTER * 

WRKAREA=YES, WORK AREA ADDRESS PRELOADED * 

SSAS=NO NO SSA'S 

When using the PL/T Optimizing Compiler, all SSAs used in DFHFC calls 
and all parameters used in CALLs must be defined as elementary items. 
This can be done by defining structures based on the same pointers as 
the structures containing the nonelementary definitions* 

DECLARE 1 DLI_CALL_SSADS BASED (BSSADS) , 
2 STORAGE_PREFIX CHAR (8) , 
2 CALL_SSA1 CHAR (*..). 
2 CALL_SSA2 CHAR (.*.); 
/* SET UP SSA1 AND USE IN CALL */ 
SSA 1KEY=SEARCH_KEY; 
DFHFC TYPE=DL/I, 

SSAS= (SSA_COUNT,CALL_SSA 1) 
CALL PLITDLI (PARM_CT , FUNCTION, PCB 1,IOKEY ,CALL_SSA1) ; 
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Operands of DFHFC Macro (DL/I) 

DLINA=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if the CICS/VS— DL/I interface is inactive. 

FUNCNS=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if a DL/I function request (a request other 
than PCB or TERM) is made and the task has no PSB scheduled. 

INVREQ=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if: (1) a DLINA, FUNCNS, LANGCON, PSBFAIL, 
PSBNA, PSBNF, PSBSCH, TASKNA, or TERMNS condition occurs and 
the associated operand is omitted, or (2) an error condition is 
detected. The errors which may be detected are: (a) the 
required data base is not in the FCT, (b) the required data 
base is not open according to the FCT, or (c) an invalid 
argument was passed to DL/I. If an INVREQ condition occurs and 
the INVREQ and an associated expansion operand (s) are both 
omitted, processing continues with the next sequential 
instruction in the application program. 

LANGCON=symbolic address (CICS/DOS/VS only) 

specifies the entry label of the user— written routine to which 
control is passed if the calling program is in a different 
source language than the called PSB. 

NORESP=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed upon normal execution of the request, that 
is, if the PSB is located and the PCB addresses are returned, 
or when the application program regains control. The CICS/VS— 
DL/I interface must have been able to pass control to DL/I and 
a DL/I pseudo— ABEND of the transaction cannot have occurred. 
The return code in the PCB must be checked to determine whether 
DL/I was able to service the request. NORESP signifies "normal 
response." If this operand is omitted, but a described 
condition applies, processing continues with the next 
sequential instruction in the application program. 

NOTOPEN=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if the data base specified in the PCB used in 
this request is logically (not necessarily physically) closed. 
The PCB does not contain a DL/I AI status code. 



PCB = 



specifies the field that contains the address of the PCB. 

symbolic address 

is the symbolic address of the field containing the address 
of the PCB. 
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(register) 

is valid only when Assembler language is used and is the 
number of a register that contains the address of the PCB. 



PSB= 



specifies the name of the PSB to be scheduled for the 
transaction . 

•psbname 1 

is the name of the PSB to be used. 

symbolic address 

is the symbolic address of an eight— byte field containing 
the name of the PSB, padded to the right with blanks. 

YES 

indicates that the name of the PSB has been placed in 
TCADLPSB by the application program. 

If this operand is omitted, the name of the program 
associated with the transaction in the CICS/VS program 
control table (PCT) is used as the PSB name. 

PSBPAIL=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if the PSB fails to initialize. 

PSBNA=symbolic address (CICS/DOS/VS only) 

specifies the entry label of the user— written routine to which 

control is passed if the task is not authorized to access this 
PSB. 

PSBNF=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if the PSB cannot be found in the PSB 
directory. 

PSBSCH=symbolic address 

specifies the entry laael of the user-written routine to which 
control is passed if a PSB is already scheduled for this task. 

SSALIST= 

indicates whether or not segment search arguments are used in 
this request and if so, identifies the list containing these 
arguments. 

YES 

indicates that a list of segment search arguments is used 
and that the address of the list has been placed in 
TCADLSSA by the application program. 

NO 

indicates that no SSA list is used in this request. 

symbolic address 

is the symbolic address of a field that contains the 
address of the SSA list. 
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(register) 

is valid only when Assembler language is used and is the 
number of a register that contains the address of the SSA 
list. 

If this operand is specified, SSAS cannot be specified. 



SSftS= 



indicates whether or not segment search arguments are used in 
this request and, if so, identifies them. 

NO 

indicates that no SSAs are used in this request. 

([ ssacount ][ ,ssa1 ][ ,ssa2,* * . ]) 

specifies the names of segment search arguments used in 
this request (thereby creating an SSA list) . The ssacount 
parameter specifies the number of SSAs to be used; it is 
the address of a fullword containing the count, or, in the 
case of Assembler language, may be expressed as a numeric 
value. Each ssa specification represents an element of the 
SSA list* The first element of an SSA list, or it may 
point to a fullword containing this count; the remaining 
elements represent addresses of SSAs. If the first element 
of an SSA list is not a count, all elements of the SSA list 
are assumed to be addresses of SSAs; the high— order bit of 
the last element of the list must be set on to indicate the 
end of the list. 

([ (register 1) ][ , (register2) ,...]) 

is interpreted as described above; that is, registerl 
contains a count of the SSAs in the list or is the first 
list entry, register2 is the first or second list entry 
(depending on whether a count has been specified), and so 
on. 

If this operand is specified, SSALIST cannot be specified. 

TASKNA=symbolic address (CICS/DOS/VS only) 

specifies the entry label of the user— written routine to which 
control is passed if the calling task is not authorized to 
access DL/I data bases. 

TERMNS=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if a termination request is made and the task 
has no PSB scheduled. 

WRKAREA= 

specifies the address of the work area to £e used. 

symbolic address 

is the symbolic address of a field that contains a pointer 
to the work area. 

YES 

indicates that the address of the work area to be used has 
been placed in TCADLIO by the application program. 
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(register) 

is valid only when Assembler language is used and is the 
number of a register that contains the address of the work 
area. 

If this operand is omitted and a Gxxx function is to be 
performed, the CICS/VS— DL/I interface acguires storage for 
the work area and returns the address of the work area at 
TCADLIOi The application program must save this address 
upon return. If any other type of function is reguested, 
the application program must provide the work area. A work 
area whose address is specified in a DPHFC macro 
instruction or placed at TCADLIO prior to execution of the 
DFHFC macro instruction includes the CICS/VS storage 
accounting area prefix. A work area specified in a CALLDLI 
or CALL statement does not* 



Chapter 3*3* DL/I Services 155 



Part 4. Data Communication Operations 
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Chapter 4.1. Introduction to Data Communication Operations 



This part describes the data communication operations Terminal Control 
(Chapter 4.2), Basic Mapping Support (Chapter 4.3), and Batch Data 
Interchange (Chapter 4.4). 

The essential differences between these data communication facilities 
is that terminal control is the basic method of communicating with 
devices whereas both Basic Mapping Support (BMS) and Batch Data 
Interchange (BDI) extend the facilities of terminal control to simplify 
further the manipulation of data streams. In fact, both BMS and BDI use 
terminal control facilities. 

Terminal Control provides specific macros and options for particular 
devices so that the application programmer can tailor his input and 
output requests according to the requirements of the devices* However, 
application programs written in this way are dependent on data 
formatting requirements of devices and therefore the application 
programmer must have detailed knowledge of the devices. 

Basic Mapping Support provides macros and options that the 
application programmer can use to format data in a standard manner. BMS 
performs the conversion of data streams provided by the application 
program to conform to the requirements of particular devices. 
Conversely, data received from a device is converted by BMS to a 
standard form. However, not all devices supported by CICS/VS can be 
used with BMS and therefore TC must be used. Also, in some cases, the 
overhead incurred to achieve data stream independence may outweigh the 
advantages. The choice as to whether BMS should be used is a matter for 
application design and is discussed more fully in the CICS/VS 
System/Application Design Guide * 

Batch Data Interchange is a set of macros that may be used either 
instead of Terminal Control macros, or in conjunction with Basic Mapping 
Support macros to communicate with the batch logical units of the 3790 
and 3770 subsystems < 
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Chapter 4.2. Terminal Control (DFHTC Macro Instruction) 



CICS/VS terminal control uses the standard access methods available with 
the host operating system. The basic telecommunications access method 
(BTAM) is used by CICS/VS for most start— stop and BSC terminals. As an 
option for OS/VS, the telecommunications access method (TCAM) can be 
specified. The sequential access method (SAM) is used where keyboard 
terminals are simulated by sequential devices such as card readers and 
line printers. The virtual telecommunications access method (ACF/VTAM) 
or the telecommunications access method (TCAM) is used for systems 
network architecture (SNA) terminal systems. 

Terminal control polls terminals to see if they have any data to 
transmit, and addresses terminals by having the computer check whether 
terminals are ready to receive data* Terminal control is responsible 
for code translation, transaction initiation, synchronization of input 
and output operations, and the line control necessary to read from or 
write to a terminal. Thus, the application program is freed from having 
to physically control terminals; During processing, an application 
program is connected to one terminal for one task and terminal control 
monitors which task is associated with which terminal. The algorithm 
used by terminal control to determine which task should be initiated is 
described later in this chapter under the heading "Terminal-Oriented 
Task Identification." Terminal control detects and logs errors, and 
also, where appropriate, inserts a default. 

Terminal control can, as its name suggests, be used for communication 
with terminals. In SNA systems, however, it is used to control 
communication with logical units. A logical unit (LU) represents either 
a terminal directly, or a program stored in a subsystem controller which 
in turn controls one or more terminals* The CICS/VS application program 
communicates, by means of the logical unit, either with a terminal or 
with the stored program. For example, a 3767 terminal is represented by 
a single logical unit without any associated user— written application 
program. In contrast, a 3790 subsystem is represented by a 3791 
controller, user— written 3790 application programs, and one or more 3 790 
terminals; when the subsystem is configured, one or more logical units 
are designated by the user. 

Facilities that apply specifically to logical units are described 
later in this chapter under "Facilities for Logical Units". 

To request terminal control services, the application programmer uses 
the CICS/VS DFHTC (terminal control) macro instruction* 

Among the services that can be requested by the DFHTC macro 
instruction are some that are of interest to most, if not all, terminal 
types supported by CICS/VS such as: 

• Write data to a terminal* 

• Read data from a terminal. 

• Synchronize terminal input /out put for a transaction. 

• Converse with a terminal. 
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• Read or write records to a card reader, disk data set, magnetic 
tape unit, or a line printer defined by the system programmer as a 
card— reader— in/line— printer— out (CRLP) terminal. This facility 
allows transactions to be tested when normal communications 
terminals are not available. 

For additional information concerning the last of these services, see 
"Sequential Terminal Support" in Chapter 7.2* 

Other services available in response to DFHTC macro instructions 
apply to specific types of terminal. Because many types of terminal are 
supported by CICS/VS, many special services are provided. (For a list 
of terminals supported by CICS/VS, see the publication CICS/VS General 
Information * ) The following list is representative of the terminal- 
oriented input/output services available: 

Read the entire contents of a buffer (3270 Information Display 
System) . 

Read a message containing both uppercase and lowercase data (3270 
Information Display System) . 

Print out the contents of an information display buffer on a 
printer (3270 Information Display System) . 

Transmit a message to a common buffer (2980 General Banking 
System) . 

Read or write data in transparent mode, that is, without 
translation (System/7, System/370, System/3, 2770 Data 
Communication System, 2780 Data Transmission Terminal, 3600 Finance 
Communication System (BTAM) , 3740 Data Entry System, 3780 Data 
Communications Terminal) * 

• Use the attention key to interrupt a write operation or signal a 
read attention request (for example, on the 2741 Communication 
Terminal) • 

The general form of the terminal control macro instruction (DFHTC) 
resembles that of other CICS/VS macro instructions. Keyword operands 
are specified separated by commas. Although most CICS/VS macro 
instructions use only one entry following the keyword TYPE, the DFHTC 
macro instruction can contain several. The 

DFHTC TYPE= (WRITE, READ) 

macro instruction, for example, causes a write to the terminal, a wait 
for that write to be completed (an implied wait) , and a read from the 
terminal to which data has just been written. 

Another example is the 

DFHTC TIPE= (ERASE, WRITE, READ, WAIT) 

macro instruction, which causes an erase and then a write to a terminal, 

followed by an implied wait, followed by a read and a requested wait. 

The latter wait ensures that the read is complete before control is 
returned to the application program. 

Two separate DFHTC macros must Jae used when two options that would be 
incompatible for the same macro are needed. Examples of incompatible 
options are: 
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DFHTC TYPE= (READ, WRITE) 

DFHTC TYPE= (WRITE, PRINT) 

DFHTC TYPE= (WRITE, READB) 

DFHTC TYPE= (PRINT, READ) 

In such cases, the first macro should include the WAIT option; for 
example: 

DFHTC TYPE= (WRITE, WAIT) 
DFHTC TYPE=READB 

As in other CICS/VS macro instruction operands, if only one entry is 
given in the TYPE operand, no parentheses are necessary. 

The application programmer must determine the combination of keywords 
that follow TYPE=, depending on the terminal (and sometimes, access 
method) used and the operations required. Additional operands may be 
required or desired, again depending upon the terminal and access method 
used. Some common input/output requests are discussed later in this 
chapter^ 

Before using the DFHTC macro instruction to request terminal 
services, the application program must include instructions that: 

1. Symbolically define the TCTTE and TIOA by copying the appropriate 
storage definitions (DFHTCTTE and DFHTIOA) provided by CICS/VS. 

(It is assumed that the storage definitions for the CSA and TCA 
have already been copied, as described in Part 2.) 

2. Establish addressability for the TCTTE by specifying a symbolic 
base address. If using the Assembler— language or COBOL, the 
application programmer must obtain the base address of the TCTTE 
from TCAFCAAA and place it in TCTTEAR; with PL/I, addressability 
for the TCTTE is established automatically. Any field in the TCTTE 
can then be accessed by field name. Addressability for the TIOA 
must be established each time a DFHTC TYPE=READ or TYPE=WRITE macro 
is issued. The ways of doing this are described in the following 
section . 



Facilities for all Terminals and Logical Units 

The facilities described in this section apply to all terminals and 
logical units. There may, however, be additional facilities that apply 
to specific devices. If this is so, details are given later in this 
chapter under headings for the relevant device types. 



READ DATA FROM A TERMINAL OR LU 

The application programmer can request that data be read from a terminal 
or logical unit by issuing the 

DFHTC TYPE=READ 

| macro instruction. This causes a read to be issued to the terminal and 
| the transaction to be placed in a wait state until the read completes. 
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The incoming data is placed in a TIOA acquired by terminal control, 
which places the address of the TIOA in TCTTEDA. On completion of the 
read operation, the application program must copy the address from 
TCTTEDA to the TIOA base address register (TIOABAR) : any field in the 
TIOA can then be accessed by field name. 

The length of the data read into the TIOA is stored in TIOATDL. 

Terminal control attempts to reuse TIOAs that have been used in 
previous operations. For this purpose, it maintains a chain of TIOA 
addresses anchored in the TCTTE. If no TIOA is attached to the chain, 
or if the existing TIOAs are too short or are otherwise unsuitable, 
| terminal control acquires a new TIOA. The current TIOA, as addressed by 
| TCTTEDA, may be freed by terminal control unless the SAVE operand is 
| specified. 

A new TIOA is also acquired by terminal control for the read when the 

DFHTC TYPE= (READ, SAVE) 

macro instruction is issued. All TIOAs currently chained off the TCTTE 
are retained and may subsequently be reused; a new TIOA is dynamically 
acquired for this read and is added to the chain* 

A write, followed by a read operation, can be specified in a single 
request. See "Write DATA and READ Response", later in this chapter. 

When a TIOA which was previously obtained as a line input— output area 
(LIOA) by the terminal control program (TCP) is passed to a user task, 
the contents of the data part cannot be guaranteed beyond the data 
length supplied in TIOATDL. Therefore users should not attempt to 
interrogate the contents of a TIOA beyond this supplied length. 

When the contents of a 3270 buffer are read (by using DFHTC 
TYPE=READB), the programmer should be aware that the attention 
identifier byte and the cursor address are made available at TCTTEAID 
and TCTTECAD respectively* A set of standard symbolic names for testing 
the 3270 attention identifier is provided in a copy book called DFHAID. 
For further details refer to "Standard Attention Identifier List 
(DFHAID)" in Chapter 4.3. "Basic Mapping Support". 



WRITE DATA TO A TERMINAL OR LO 

A request for data to be written to a terminal or logical unit can be 
issued using the 

DFHTC TYPE=WRITE 

macro instruction. Before issuing this macro instruction, the 
application program must acquire a TIOA in which to build the data to be 
transmitted, and must place the address of the TIOA in TCTTEDA and the 
length of the data to be written in TIOATDL* The maximum data length is 
32,76 7 bytes which includes the length of the function management header 
(FMH) when writing to a logical unit. 

The required TIOA is acquired by a DFHSC TIPE=GETMAIN,CLASS=TERMINAL 
macro instruction. CICS/VS places the address of the TIOA in TCASCSA , 
from where it must be copied into the TIOA base address register 
(TIOABAR) . 
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The application program must not change the contents of TCTTEDA until 
after the I/O operation has completed. The operation will only be 
complete when another terminal control request has been issued (that is, 
TYPE=WAIT or TYPE=READ) . 

If WAIT is not specified on a terminal control TYPE=WRITE operation, 
the operation may be deferred until the next terminal control request. 
When the next terminal control request is issued, the SNA flows are 
optimized before the actual I/O is issued. For example, a terminal 
control write followed by a terminal control read could cause two flows 
to be sent, whereas only one flow is sent if it can be determined that 
the next operation is a read request. 

When writing data to a 3600 (non— pipeline) or 3790 inquiry logical 
unit, the CICS/VS application program must not put data into the first 
three bytes of the TIOA, unless it is building its own FMH (see 
"Function Management Header" later in this chapter) . The FMH is built 
either by CICS/VS or by the CICS/VS application program. 

When the write operation is completed by terminal control, the TIOA 
is released to a dynamic storage pool (unless SAVE is specified) . 
Subsequent reference to this TIOA Jay the application program will 
produce unpredictable results. 

However, a TIOA can be reused by the application program after a 
write if the request to write data to a terminal uses the 

DFHTC TYPE= (WRITE , SA VE , WAIT) 

macro instruction! In this case, the TIOA is not released by terminal 
control* The WAIT parameter ensures that the write of the TIOA is 
| complete before the area is reused. Note that the SAVE operand does not 
I guarantee that the field TCTTEDA addresses the TIOA saved, but only that 
| the TIOA is not freed. 

If a dump of the TIOA is required following a terminal control write, 
the SAVE and WAIT operands should be included with the DFHTC TYPE=WRITE 
macro instruction that precedes the DFHDC macro instruction. 



WRITE DATA AND READ REPLY 

As stated earlier, a write followed by a read operation can be specified 
in a single request by issuing the 

DFHTC TYPE= (WRITE, READ) 

macro instruction. A typical use for this macro instruction occurs in a 
conversational environment in which the application program writes a 
guestion to the terminal, waits for a reply, and subsequently reads the 
reply. Because the SAVE parameter is not specified, terminal control 
can reuse the TIOA (from which data is written) as a TIOA for the input 
data. Under certain conditions, however, a new TIOA is obtained for the 
read operation, for example: 

• Local 3270 terminals* 

• PSEUDOBIN specified with READ, WRITE. 
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• The TIOA length for the WRITE instruction less than that specified 
by the system programmer in the DFHTCT TYPE=TERMINAL,TIOAL=length 
specification (binary synchronous terminals) or in the DFHTCT 
TYPE=LINE,INAREAL=length specification (all other terminals) . 

• Certain error conditions. 

• A 3270 terminal used in 2260 compatibility mode. 

The user should alway s reload TIOABAR from TCTTEDA following the 
(WRITE, RE AD) macro instruction* 

For a terminal connected to the 7770 Audio Response Unit, a read 
reguest that does not include the WRITE parameter causes the "ready" 
message (defined in the terminal control table by the system programmer) 
to be written to the terminal before the read operation occurs. 

If both a write and a read operation are specified in a single 
reguest by issuing 

DFHTC TYPE= (WRITE, READ, SAVE) 

the TIOA used for writing is saved; a new TIOA is then acquired by 
terminal control for the read. The size of the TIOA is determined by 
the system programmer when specifying the TCTTE for the terminal (rather 
than by the size of the TIOA used for the write). If the saved TIOA is 
reused later for either writing or reading, the application program must 
place the address of the TIOA into TCTTEDA prior to issuing the reguest 
to use the area. 

The manner in which the address of a TIOA is "remembered" is the 
application programmer^ responsibility. 

Upon completion of a (WRITE, READ, SAVE) , place the value at TCTTEDA 
into TIOABAR to establish addressability for the newly-acquired TIOA* 



SYNCHRONIZE TERMINAL I/O (WAIT) 

In a task under which more than one terminal or logical unit operation 
is performed, the application programmer must ensure that a current 
terminal operation is complete before another begins. Therefore, after 
a terminal control write has been issued, but before another terminal 
control write can be issued, a terminal control wait must be issued. 
TCTTEDA can be changed to point to the new TIOA for output, and the next 
terminal control write can be issued. For SNA logical units, after a 
terminal control write has been issued, the next operation may be either 
a terminal control wait, or a terminal control read, according to 
whether a subsequent write, or terminal control read is to be issued. 
To do this the 

DFHTC TYPE=WAIT 

macro instruction is issued, where the WAIT parameter is coded 
separately, as shown, or in combination with READ or WRITE. A PUT can 
be coded in place of a (WRITE, WAIT) ; a GET can be coded in place of a 
| (READ, WAIT)* A terminal control read operation forces a wait to occur 
j before the transaction is resumed, that is, the data will be available 
| in the TIOA addressed by TCTTEDA at completion of the terminal control 
| read operation* 
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A wait may cause execution of a task to be suspended. If suspension 
is necessary, control is returned to CICS/VS. Execution of the task is 
| resumed when the write is posted complete* 

A wait need not be coded for a write if the write is the last 
terminal operation of the transaction- The TIOA is retained until the 
data is written, even if the transaction and its associated storage are 
deleted from the system before the write occurs. 



CONVERSE WITH A TERMINAL OR LO 

To request a conversational mode of communication with a terminal or 
logical unit, issue the 

DFHTC TYPE=CONVERSE 

macro instruction, where CONVERSE (or CONV) is the same as 

(WRITE, READ, WAIT) . This instruction is always executed in the sequence: 

WRITE, implied wait, READ, WAIT. 

It is possible, for most devices, to use this macro instruction 
rather than TYPE=READ, but it must not be used for the 3600 or 3650 
pipeline logical units. However, its use is recommended for all other 
logical units* 



DISCONNECT A SWITCHED LINE 

To break a line connection between a terminal or logical unit and a host 
CPU, the 

DFHTC TIPE=DISCONNECT 

macro instruction is used* This applies only to devices operating on 
switched lines or to logical units. When used with logical units, 
DISCONNECT, which does not become effective until the task has been 
terminated, terminates the session, without causing a physical 
disconnection . 

Note ; CICS/OS/VS implements DISCONNECT for World Trade Teletype 
Terminals by writing a message to the terminal indicating that the 
terminal operator should manually disconnect; 



E xamples 

The following examples show the coding required to: 

1. Acquire storage for use as a terminal input/output area through the 
DFHSC macro instruction* 

2. Place the address of the acquired area into TCTTEDA. 

3* Place the length of the data to be written into TIOATDL. 
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Issue a terminal control macro instruction to a 3270 terminal, thus 
erasing the screen, returning the cursor to the upper left corner 
of the screen, writing to the terminal, and reading from the 
terminal (allowing terminal control to manage storage for the 
TIOA ) . 

Establish addressability to the TIOA into which the data was read. 



IFor Assembler Lancruaae 


ESTABLISH ADDRESSABILITY FOR TCTTE 


_. — , 


| L TCTTEAR,TCAFCAAA 




| DFHSC 


TIPE=GETMAIN, 


OBTAIN TIOA FOR OUTPUT DATA 


* 1 




NUMBYTE=80, 




* 1 




CLASS=TERMINAL 






1 L 


TIOABAR,TCASCSA 


ADDRESS OF TIOA 




| ST 


TIOABAR,TCTTEDA 


PLACE OUTPUT ADDRESS IN TCTTE 




| MVC 


TIOADBA (80), DATA 


PLACE DATA IN TIOA 




| MVC 


TIOATDL,=H»80* 


PLACE DATA LENGTH IN TIOATDL 




| DFHTC 


TYPE= (WRITE, ERASE, 


ERASE SCREEN, WRITE TO 


♦ 1 




READ, WAIT) 


TERMINAL, THEN READ 




1 I* 


TIOABAR,TCTTEDA 


ESTABLISH ADDRESSABILITY FOR TIOA 




IFor COBOL 


• 


NOTE EST ADDRESSABILITY FOR TCTTE. 




| MOVE TCAFCAAA TO TCTTEAR* 




| DFHSC 


TTPE=GETMAIN, 


OBTAIN TIOA FOR OUTPUT DATA 


* 1 




NUMBYTE=80, 




* 1 




CLASS=TERMINAL 






| MOVE 


TCASCSA TO TIOABAR* 


NOTE ADDRESS OF TIOA 




| MOVE 


TIOABAR TO TCTTBDA. 


NOTE PLACE ADDR OF TIOA IN TCTTE. 




| MOVE 


DATA TO TIOADATA. 


NOTE PLACE DATA IN TIOA (TIOADATA 
USER DEFINED) . 


IS | 


| MOVE 


80 TO TIOATDL. 


NOTE PLACE DATA LENGTH IN TIOATDL. 




| DFHTC 


i 
d 

TYPE= (WRITE, ERASE, 


ERASE SCREEN, WRITE TO 


* 1 




READ, WAIT) 


TERMINAL, THEN READ 




| MOVE 


TCTTEDA TO TIOABAR. 


NOTE EST ADDRESSABILITY FOR TIOA. 




IFor PL/I: 








| TCTTEAR= 


=TCAFCAAA; 


/♦EST ADDRESSABILITY FOR TCTTE*/ 




| DFHSC 


TYPE=GETMAIN, 


OBTAIN TIOA FOR OUTPUT DATA 


* 1 




NUMBYTE=80, 




♦ 1 




CLASS=TERMINAL 






| TI0ABAR= 


=TCASCSA; 


/♦ADDRESS OF TIOA*/ 




| TCTTEDA= 


=TIOABAR; 


/♦PLACE ADDR OF TIOA IN TCTTE*/ 




| TI0DATA= 


=data; 


/♦PLACE DATA IN TIOA (TIODATA IS 
USER-DEFINED) ♦/ 




| TIOATDL= 


= 80; 


/♦PLACE DATA LENGTH IN TIOATDL*/ 




| DFHTC 


4 

TYPE= (WRITE, ERASE, 


ERASE SCREEN, WRITE TO 


* 1 




READ, WAIT) 


TERMINAL, THEN READ 




| TIOBAR=TCTTEDA; 


/♦EST ADDRESSABILITY FOR TIOA*/ 
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Facilities for Logical Units 

A CICS/VS application program communicates with a TCAM, VTAM, or EXTM 
logical unit in much the same way that it does with BTAM or TCAM 
terminals (that is, by using the various forms of the DFHTC macro 
instruction described above) . However, communication with logical units 
is governed by the conventions (protocols) that apply to each type of 
logical unit. This section describes the additional facilities provided 
by CICS/VS to enable the application programmer to comply with these 
protocols . 

The types of logical units and the related protocols for each of the 
SNA subsystems supported by CICS/VS are described in the CICS/VS 
subsystem guides for the IBM 3270, IBM 3600/3630, IBM 3650, IBM 
3767/3770 and the IBM 3790 (see Bibliography) . 



SEND/RECEIVE MODE 

For SNA logical units, a transaction conversing with such a logical unit 
must conform to the send/receive protocols of SNA, unless the read— ahead 
gueueing feature has been specified* 

However, a transaction is normally in send mode and can issue any 
terminal control request. For displays (for example, the 3270), the 
send/receive mode is transparent to the application program, but for 
logical units that perform chaining, or make use of the full SNA 
protocols (for example, the 3767), the send/receive mode should be taken 
into account. 

If the application program is in receive mode, flag TCTEURCV in field 
TCTERCVI is set on, and the application program must continue to issue 
terminal control READ requests. 

For compatibility, the read— ahead gueueing feature (RAQ=YES specified 
in the DFHSG PROGRAM=TCP system macro ) is provided so that the 
application program is independent of the send/receive mode. However, 
it is recommended that application programs be changed to use SNA 
send/receive protocols and that, wherever possible, they specify RAQ=NO. 



OVERLAPPING LOGICAL-UNIT OUTPUT 

Write operations are not initiated until a subsequent terminal control 
operation to the logical unit is issued, a syncpoint is taken, or the 
task terminates. 

If a terminal control write operation is awaiting completion, a 
terminal control wait should be issued unless the next operation is a 
read reguest, in which case a terminal control read can be issued 
directly. 

A terminal control write and wait request causes the operation to be 
initiated immediately* If only a terminal control write is issued, the 
operation is delayed until the next operation so that SNA flow handling 
can be improved. 

The point at which a wait is satisfied depends upon whether task 
protection, message integrity, or DEFRESP=YES is reguested for the task. 
Task protection and message integrity are specified, by the system 
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programmer, in the DFflPCT macro instruction; if data is sent with task 
protection or message integrity, a wait is completed when a logical unit 
responds to the write reguest; otherwise, the wait is completed after 
VTAM has accepted the output reguest* 

If a task is operating under task protection or message integrity and 
an exception response is returned for an output reguest, the output 
message is still available in the TIOA. The node error program (NEP) 
can therefore reguest that the operation be retried as many times as 
specified by the installation* 



CHAINING OF INPUT DATA 

For transmission purposes, data handled by a logical unit is divided 
into reguest/response units (BUs) * The data may be transmitted as one 
or more RUs, called a chain, depending on the length of the data, and on 
the maximum size of the RU defined for the logical unit or that has been 
defined for the terminal network in general. 

Each RU contains a set of indicators that specify whether the RU is 
the first, middle, or end, of the chain (FOC, MOC, or EOC, 
respectively). If the chain consists of only one RU, this RU contains 
both the FOC and the EOC indicators. 

Data is transmitted as a chain of one or more RUs from a logical unit 
to the application program. If the chain contains more than one RU, 
further read reguests are required, one for each RU, unless chain 
assembly has been specified. (Chain assembly is described later in this 
chapter.) The length of each RU must be less than or equal to the 
maximum RU size* 

| The EOC operand of the DFHTC TYPE=READ macro is used to test for the 
presence of the EOC indicator. If it is present, that is, the complete 
chain has been received, control is passed to a user— written routine 

| that provides additional processing. 

For some logical units, the data transmitted may contain a function 
management header (FMH), in which case, inbound— FMH processing will take 
precedence over EOC processing. (Inbound FMH is described later in this 
chapter.) 

Further, if the FMH indicates the end of the data set, control will 
be passed to the EODS routine instead of to the INBFMH or EOC routines. 
THe DFHTC TIPE=WAIT macro with the EOC operand specifies that control is 
to be passed to an EOC routine from within either the inbound FMH or the 
EODS routine. 

An FMH may also occur in the first RU of a chain that contains more 
than one RU. In this case, control is passed to the INBFMH routine when 
a DFHTC TTPE=READ is satisfied by that RU * 

The application program must read all the data from the logical unit, 
that is, it should not terminate (except abnormally) before EOC has been 
received* Application programs should also ensure that the complete 
data stream has been received from the logical unit; this will be 
ensured as long as the application program is not in receive mode when 
it terminates. 
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CHAINING OF OUTPUT DATA 

As in the case of input data, output data is transmitted as 

request/response units (RUs) * If the length of the data supplied in the 

TIOA exceeds the RU size, CICS/VS automatically breaks up the data into 

RUs and transmits these RUs as a chain. During transmission from 

CICS/VS to the logical unit, the RUs are marked FOC, MOC, or EOC to 

denote their position in the chain. An RU that is the only one in a 
chain is marked OC (only— in-chain) . 

If the system programmer specified that the application program can 
control the chaining of outbound data, the application program can 
inhibit the end— of— chain marker on the last (or only) RU resulting from 
the write request by including the CCOMPL=NO operand (specifying that 
the chain is not yet complete) . The data supplied in the TIOA for the 
next write request is treated as a continuation of the chain. 



CHAIN ASSEMBLY 

Chain assembly, which is specified by the system programmer in the 
TCTTE, is the process of assembling RUs together to form a chain which 
is transmitted as an entity to the application program in a single TIOA 
in response to a single read request. This ensures the integrity of the 
whole chain prior to presentation to the application program. If the 
EOC operand is specified in the read request, the EOC routine receives 
control for every read request (except when an FMH is received and the 
appropriate EODS or INBFMH routine is specified, as described earlier in 
this chapter under "Chaining of Input Data" . ) 

The length of the TIOA required to accommodate a chain is unknown 
since a chain can consist of any number of RUs. To allow for this, two 
TIOA lengths can be specified in the TCTTE by the system programmer. 
The first length specifies a TIOA that will normally be provided. The 
second specifies a larger TIOA for use when the normal TIOA is not large 
enough. If the larger TIOA cannot hold the complete chain, the node 
abnormal condition program (DFHZNAC) is invoked and the task is 
terminated abnormally. Additional processing of the chain can, however, 
be initiated by the node error program (DFHZNEP) when a further read 
request will r>e needed to cause transmission of the rest of the chain. 
The use of two TIOA sizes minimizes storage requirements. 

Chain assembly is recommended for most interactive applications, 
since the input data is usually made up of a chain of more than one RU. 
In many cases the application program logic is simplified by use of this 
option. 



LOGICAL RECORD PRESENTATION 

Normally a chain contains the data to be processed and this chain is 
presented to the application program in a TIOA as specified in the 
TCTTE. 

In some cases, however, the chain contains many logical entities for 
processing. These may be each RU itself, or the RUs may be further 
subdivided into logical records delimited by inter— record separator 
control characters, or new line characters. 
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The entire RU will be presented to the application program if chain 
assembly is not specified in the TCTTE. However, if the data stream is 
delimited by separators into logical records, the system programmer can 
specify in the PCT that logical records will be presented to the 
application program instead of RUs or chains, so overriding on an 
application basis the TCTTE options for the logical unit. 

If the RU contains more than one logical record, the records will be 
separated by NL (new line) , IRS (inter— record separator) , or TRN 
(transparent) characters. Except in the case of LUTYPE4 , one logical 
record cannot be transmitted in more than one RU; the end of the RU is 
always the end of the logical record. Data from an LUTYPE4 unit may 
contain logical records that span RUs, in which case chain assembly 
should be specified. 

Since a card reader inserts an IRS character after the last non— blank 
character on the card, the user may receive card images that are less 
than 80 characters in length. Conversely, a series of full cards will 
begin at 8 1— character intervals . 

Por those application programs for which this option is specified, 
each read request results in one logical record being presented to the 
application program in a TIOA, regardless of whether chain assembly is 
specified or not. If the logical records are separated by IRS or TRN 
characters, these are removed, and do not appear in the TIOA* 
Therefore, a blank card will appear as a TIOA with a length of zero. If 
NL characters are used to separate the logical records, they are not 
removed, and the NL character from the end of each logical record 
appears at the end of the TIOA* All the previously— described 
communication features are still in operation. That is, notification of 
end— of— chain conditions, and (for batch logical units only) notification 
of end— of— data— set conditions and presentation of the inbound FMH at the 
beginning of a chain, still occurs. 

If chain assembly has been specified, a logical record ends with a 
delimiter (either NL, IRS, or TRN) , or the end of the assembled chain. 
The end of chain notification is given with the last logical record of 
the chain. 



DEFINITE RESPONSE 

The type of response reguested by CICS/VS for outbound data is generally 
determined by the system programmer when generating the PCT. The system 
programmer can specify that all outbound data for an application program 
will require a definite response, or allow the exception— response 
protocol to be used, which means that a response will be made only if an 
error situation occurs* 

The use of definite— response protocol has some performance 
disadvantages, but may be necessary for some application programs. To 
provide a more flexible method of specifying the protocol to be used, 
the DEFRESP operand is provided for use on the DFHTC TYPE=WRITE macro 
instruction * One example of the use of this operand is to request a 
definite response for every tenth write request, exception response 
being the general rule. 

Because a response cannot be received until the whole chain has been 
sent, the DEFRESP operand and the CCOHPL=NO operand are mutually 
exclusive. The DEFRESP operand and the ERASE operand are also mutually 
exclusive. 
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FUNCTION MANAGEMENT HEADER (FMH) 

A function management header (FMH) is a field that can be included at 
the beginning of an input or output message. It is used to convey 
information about the message and how it should be handled. 

For some logical units, the use of an FMH is mandatory, for others it 
is optional, and in some cases FMHs cannot be used at all. 

For output, the FMH can be built by the application program or by 
CICS/VS. For input, the FMH can be passed to the application program or 
it can be suppressed by CICS/VS. 

The rules governing the use of FMHs for each type of logical unit, 
and the formats of the FMHs, are given in the CICS/VS subsystem guides 
(for example, the CICS/VS IBM 3790 Guide ) , which are listed in the 
Bibliography. 



Inbound FMH 

The CICS/VS application program can reguest notification when an FMH is 
included in the data received during a read from a logical unit; when 
present, the FMH is at the start of the TIOA. 

Whether or not inbound FMHs will be passed to the application program 
is specified by the system programmer in the PCT. It can be specified 
that no inbound FMHs will be passed, or that only the FMH indicating end 
of data set (EODS) will be passed, or that all inbound FMHs will be 
passed, or that the data interchange program (DFHDIP) will process the 
FMH* 

The INBFMH operand of the DFHTC TYPE=READ or WAIT macro instruction 
specifies that control is to be passed to a user— written routine 
whenever an inbound FMH is received. Use of the INBFMH operand implies 
that the WAIT option of the TYPE operand is in effect. 

The user— written routine can examine the FMH and take some action 
depending on, for example, from which device the data has come. The 
routine then scans the TIOA for input data, starting after the FMH. If 
the data is initial data from a logical unit, the transaction 
identification will start after the FMH. 

When input data is received as a chain of RUs, only the first (or 
only) RU of the chain contains an FMH. 



Outbound FMH 

Some logical units require or allow control information to be specified 
by means of an FMH* For 3600 ( no n— pipeline) and 3790 inquiry logical 
units, CICS/VS will build the FMH, but the application program must 
reserve space in the TIOA for it. CICS/VS will not build on FMH for any 
other type of logical unit. 

If the FMH is to be built by the application program, the write 
request must specify FMH=YES. The FMH must start at the beginning of 
the TIOA. 
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END OF DATA SET (EODS) 

The DPHTC TYPE=EODS macro specifies that an FMH containing an EODS 
indicator is sent to a 3650 interpreter logical unit. This FMH delimits 
the output. The end of the input is detected similarly by the EODS 
operand of a DFHTC TYPE=READ macro. 



LOGICAL DEVICE CODE (LDC) 

A logical device code (LDC) is a code that can be included in an 
outbound FMH to specify the disposition of the data (for example, to 
which subsystem terminal it should be sent) . 

An LDC is a CICS/VS— supported and installation-defined logical device 
code. Each code can be represented by a unique LDC mnemonic. The 
installation can specify up to 256 two— character mnemonics for each 
TCTTE, and two or more TCTTEs can share a list of these mnemonics. 
Corresponding to each LDC mnemonic for each TCTTE is a numeric value 
(the LDC itself whose code value can range from to 255) . A device 
type and a logical page size are also associated with each LDC. "LDC" 
or "LDC value" is used in this publication to refer to the code 
specified by the user. "LDC mnemonic" refers to the two-character 
symbol that represents the LDC numeric value. 

Within the 3601 subsystem, a user— written application program 
provides the function of the logical unit. For batch and batch data 
interchange logical units the functions of the logical unit are built in 
and in general cannot be modified further by the user. The following 
paragraphs discuss some of the functions that may be provided in a user- 
written application program 

When a CICS/VS application program issues a write request with the 
LDC operand specified, the numeric value associated with the mnemonic 
for the particular TCTTE is inserted in the FMH. The numeric value 
associated with the LDC mnemonic is chosen by the installation; the 
interpretation of that numeric value is the responsibility of the 
subsystem application program. 

As a minimum, the installation can choose a different LDC to 
correspond to each device attached to the logical unit. The values 
(codes) chosen for the LDC can correspond exactly to the logical device 
address (LDA) for each device. The subsystem application program can 
then take the CICS/VS output data and write it directly to the indicated 
LDA* 

LDCs can be used to provide support for multiple— form printers. When 
used for these printers, each LDC within a specified range corresponds 
to a particular type of form. Whenever the subsystem application 
program receives data with an LDC that indicates a particular printer 
and a particular form, the application program can check the device to 
determine whether the correct form is currently on the printer. If the 
correct form is on the printer, the application program proceeds with 
the output operation. If the correct form is not on the printer, the 
application program can request the operator to load the appropriate 
form and to signal when the load is completed. 

Some LDCs can be used to indicate certain standard actions to be 
undertaken by the application program. Using the LDC in this way can 
reduce the overhead of writing messages to the subsystem application 
program. An example of this use of LDCs is an instruction to the 
application program to turn on specific indicator lights on a device. A 
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range of LDCs can be specified for each device, each LDC within this 
range corresponding to a specific light ± Upon receipt of such an LDC, 
the application program determines the appropriate device and indicator 
and issues the commands necessary to turn on the light. Other standard 
actions that can be invoked by LDCs are dumping operator totals, 
checking diskettes for transaction backlogs, or indicating a change in 
operational mode. 

The LDC operand of the DFHTC TYPB=WRITE macro is only for use with 
3600 (3601) non-pipeline logical units and provides a symbolic way of 
conveying to CICS/VS the type of FMH it is to build on behalf of the 
application program. Alternatively, the application program may build 
its own FMH (which may be greater than three bytes) and indicate this by 
means of the FMH operand. 

Component or destination selection for batch and batch data 
interchange logical units is accomplished by means of an FMH, the length 
of which depends on the type of logical unit. The application program 
must build its own FMH, or use the LDC operands of the basic mapping 
support (BMS) macros DFHMSD or DFHBMS TYPE=00T or TIPE=STORE to instruct 
BMS to build the correct FMH. If the FMH is to be built by the 
application program the DFHTC CTYPE=LOCATE, LDC=YES macro may be used to 
symbolically obtain the component selection value to be inserted in the 
appropriate FMH field. Refer to the IBM 3770 and IBM 3790 guides for a 
further discussion of component selection. 



UNSOLICITED INPUT 

If a task is in progress and unexpected data (that is, data from a 
terminal for which a read reguest has not been issued) arrives from a 
start—stop or BSC terminal, CICS/VS ignores the data and it is lost. 

If, however, unexpected data arrives from a 3600, 3650, 3767 or 3770 
interactive (contention only) , or 3790 inguiry logical unit, it is 
gueued and is used to satisfy any future input reguests for that logical 
| unit. For the 327 logical unit (but not for the 3 270 LUTYPE2 logical 
| unit, data is gueued only if PUNS0L=N0 is specified in the DFHSG 
PROGRAM=TCP macro; otherwise it is lost. Unsolicited input does not 
occur for the other logical units* 



SIGNAL COMMANDS FROM LOGICAL UNITS 

Signal data— flow— control commands from the logical unit must be handled 
by the application program. The DFHTC TYPE=SIGNAL macro instruction 
allows an address to be specified to which control will pass when a 
signal command is received. The associated signal code will be stored 
in the four— byte field TCTESIDI in the terminal control" table terminal 
entry (TCTTE) . 

If a hard reguest— change— direction (RCD) signal is received from an 
LUTYPE4 unit (signal code = X» 00010000 ■) , the transaction should either 
end or read data from the logical unit. Any attempt to write to the 
unit immediately following a hard RCD would be an error, indicated by 
the flag TCTERCD in the TCTTE. If a further attempt to write to the 
logical unit is made, CICS/VS will abnormally terminate the transaction 
with an abend code of ATCL. 

Most logical units that can send a signal command with a code of 
X» 00010000* do so when an attention key is pressed. 
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BRACKET PROTOCOL 

The use of bracket protocol is a means of preventing interruption of the 
exchange of data between CICS/VS and a logical unit. CICS/VS or the 
logical unit may send begin— bracket, but only CICS/VS may send the end- 
bracket. Brackets can delimit a conversation between CICS/VS and the 
logical unit or merely the transmission of a series of data chains in 
one direction* 

Bracket protocol is used when CICS/VS communicates with a logical 
unit i The use of brackets is usually transparent to the CICS/VS 
application program. 

Only on the last write operation of a task to a logical unit does the 
bracket protocol become apparent to the CICS/VS application program. On 
the last output request to a logical unit, the CICS/VS application 
program may specify LAST in the DFHTC TYPE=WRITE macro instruction. The 
last output request is defined as either the last DFHTC TIPE=WRITE macro 
specified for a task without chain control; or as the write operation 
that transmits the FOC or OC marker of the last chain of a transaction 
with chain control. 

The LAST specification causes CICS/VS to transmit an end— bracket 
indicator with the final output message to the logical unit* This 
indicator notifies the logical unit that the current transaction is 
ending. If the LAST operand is not specified, CICS/VS waits until the 
task detaches before sending the end— bracket indicator. Since an end- 
bracket indicator is transmitted only with the first RU of a chain, the 
LAST operand is ignored for a transaction with chain control unless FOC 
or OC is also specified. Refer to the publication VTAM Concepts and 
Plannin g for more details on bracket protocol. 
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Terminal-Oriented Task Identification 

When CICS/VS receives input from a terminal to which no task is 
attached, it has to determine which transaction should be initiated. 
The methods by which the user can specify the transaction to be 
initiated and the sequence in which CICS/VS checks these specifications 
are as follows (see also Figure 1.2— 1). 

I Te st 1 ; Is the input from a PA key (of a 3270 terminal) that has been 
I defined at system initialization as the print request key? 

| If yes, printing of the data displayed on the screen is 

initiated. 

Test 2 : a) Is this terminal of a type supported by the basic mapping 
support terminal paging facility? 
b) Is the input a paging command? (The terminal operator can 
enter paging commands defined by the system programmer in 
the DFHSIT macro instruction. See the CICS/VS 
System Programmer's Reference Manual .) 

If yes to both (a) and (b) , the transaction CSPG, which 
processes paging commands, is initiated. 

I Test 3 : If an attach FMH is present in the data stream and Tests 4 and 
| 5 are not fulfilled, the transaction specified in the attach 

I FMH is initiated i The architectured attach names are converted 

| to "CSMI". 

Test 4 ; Does the terminal control table entry for the terminal include 
a transaction identification (specified by the TRANSID 
operand of the DFHTCT macro)? 

If yes, the specified transaction is initiated. 

Test 5 ; Is a transaction specified by the TRANSID operand of a DFHPC 
TYPE=RETURN macro instruction (or by the application program 
moving the transaction name into TCANXTID)? 

If yes, the specified transaction is initiated. 

Test 6 ; a) Is the terminal a 3270 (including 3270 logical unit and 
3650 host— conversational (3270) logical unit, connected 
via VTAM?) 

b) Is the input from a PA key, PF key, light pen attention 
(LPA) , or magnetic stripe card reader (OPID) ? 

c) Is this input (PA, PF, LPA, or OPID) specified by the 
TASKREQ operand of a DFHPCT TYPE=ENTRY macro instruction? 
(See the CICS/VS System Programmer's Reference Manual .) 

If yes to (a), (b), and (c) , the program specified by the 
PROGRAM operand of same DFHPCT TYPE=ENTRY macro instruction 
is given control. 

Test 7 ; Is a valid transaction identification specified by the first 
one to four characters of the terminal input? 

If yes, the specified transaction is initiated. 

For all PA keys and some LPAs there cannot be terminal input. 
If there is no terminal input an "invalid transaction 
identification" message is sent to the terminal. 
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If none of the above tests is met, an invalid transaction 
identification exists. Message DFH2001 is sent to the terminal. 

Note : The 3735 Programmable Buffered Terminal makes an exception to 
this sequence when operating in inquiry mode* The test of input from 
| the terminal (Test 7 above) is given highest priority. 



Yes 




Initiate 
Printing 




Yes 



Initiate CSPG 




Yes 




No 




Yes 



Initiate specified 
transaction 



Yes 



Initiate specified 
transaction 



Yes 




Yes 




Send "invalid 
transaction ident." 
message to terminal 



Initiate transaction 

specified by 

terminal input 




Yes 




Yes 



Initiate transaction 
specified in 
Attach FMH 



Initiate transaction 

specified by 
terminal input AID 



I Figure 4*2—1* Terainal-Oriented Task Identification 
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Syntax of the DFHTC Macro Instruction 

This section shows the syntax of the DFHTC macro instruction available 
for use with each type of device or logical unit, arranged in numerical 
order. 

The syntax displays for each device and for the 32 70 logical unit are 
followed by information specific to that device or logical unit. 
However, information about 3600, 3650, 3767, 3770, and 3790 logical 
units is given in the CICS/VS subsystem guides. 



TCAM SUPPORTED TERMINALS AND LOGICAL UNITS (CICS/OS/VS ONLY) 

Under CICS/OS/VS only, because TCAM permits many applications to share a 
single network, the CICS/VS TCAM interface supports data streams rather 
than specific terminals or logical units. 

Operations for terminals and logical units connected through TCAM use 
the same operands as the terminals and logical units connected through 
the other access methods used with CICS/VS. 

For input, TCAM supports only the READ And READL operations. For 
output, TCAM supports only the WRITE and HRITEL operations with the 
optional use of ERASE. The DEST operand can be specified for all TCAM 
output operations. (The syntax of the DFHTC macro for TCAM operations 
is given later in this chapter.) 

The 2260 compatibility option is not available for 3270 connected 
through TCAM . 

3650 logical units cannot be connected through TCAM. 



BTAM PROGRAMMABLE DEVICES 

When BTAM is used by CICS/VS for programmable binary synchronous 
communication line management, CICS/VS initializes the communication 
line with a BTAM read initial (TI) ; the terminal response must be a 
write initial (TI) or the equivalent. If a user— written application 
program then issues a read, CICS/VS issues a read continue (TT ) to that 
line; if the application program issues a write, CICS/VS issues a read 
interrupt (RVI) to that line. If end of transmission (EOT) is not 
received on the RVI, CICS/VS issues a read continue (TT) until the EOT is 
received. When TCAM is used, all of this line control is handled by the 
MCP rather than by CICS/VS. 

The programmable terminal response to a read interrupt must be "end 
of transmission" (EOT). The EOT response may, however, be preceded by 
writes, in order to exhaust the contents of output buffers; this is 
provided the input buffer size is not exceeded by this data. The input 
buffer size is specified by the system programmer during preparation of 
the terminal control table. CICS/VS issues a read continue until it 
receives an EOT, or until the input message exceeds the size of the 
input buffer (an error condition). 

After receiving an EOT, CICS/VS issues a write initial (TI) or the 
equivalent (depending on the type of line) . The programmable terminal 
response must be a read initial (TI) or the equivalent. 
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If another write is issued by the application program, CICS/VS issues 
a write continue (TT) to that line. If the application program issues a 
read after it has issued a write, CICS/VS turns the line around with a 
write reset (TR). (CICS/VS does not recognize a read interrupt.) 

When CICS/VS initiates a transaction using the automatic transaction 
initiation facility, it first of all issues a write initial (TI) or the 
equivalent* The terminal must respond with a read initial (TI) or the 
equivalent. Reading from or writing to the terminal can then continue 
as if the write initial had been caused by a write instruction in the 
application program. 

To ensure that binary synchronous terminals (for example, System/370, 
1130, 2780) remain coordinated, CICS/VS processes the data collection or 
data transmission transaction on any line to completion, before polling 
other terminals on that line. 

The programmable terminal actions required for the above activity, 
with the corresponding user application program macro instructions and 
CICS/VS actions, are summarized as follows: 



Application Program 


CICS/VS (note 1) | 


— i 
Programmable | 
Terminal Program | 






Read initial (TI) 


Write initial (TI) | 


DFHTC TYPE=READ 




Read continue (TT) 


Write continue (TT) | 


DFHTC TYPE=WRITE (note 
(note 


2) 
3) 


Read interrupt (RVI) 
Read continue (TT) 

Write initial (TI) 


Write reset (TR) , or | 
Write continue j 
Write reset | 
Read initial (TI) | 


DFHTC TYPE=WRITE 




Write continue (TT) 


Read continue (TT) | 


DFHTC TYPE=READ (note 


«») 


Write reset (TR) 
Read initial (TI) 


Read continue (TT) | 
Write initial (TI) | 



Notes : 

1. CICS/VS issues the macro instruction shown, or, if the line is 
switched, the equivalent. The user— written programaable terminal 
program must issue the equivalent of the BTAM operation shown. 

2. An RVI sequence is indicated by the DECFLAGS field of the data 
extent control block (DECB) beinq set to X , 02 l and a completion 
code of X'JF* beinq returned to the event control block (ECB) . 

3. The read continue is issued only if the EOT character is not 
received on the read interrupt. 

4. Write reset is issued only for point— to— point terminals. 

Input data is deblocked to ETX, ETB, RS, and OS characters. These 
characters are moved with the data to the TIOA but are not included in 
the data lenqth (TIOATDL) . The CICS/VS application proqrammer should be 
aware that characters such as NL, CR, LF, and EM are passed in the TIOA 
as data. 
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TELETYPEWRITER PROGRAMMING 

The teletypewriter (World Trade only) uses two different control 
characters for print formatting: 

< carriage return, (X»22» in ITA2 code or X'15 1 in EBCDIC) 

= line feed, (X^S 1 in ITA2 code or X«25» in EBCDIC) 

The application programmer should always use < first; that is <= or 
< === , but never =<, otherwise following characters (data) may be printed 
while the typebar is moving to the left. 



M essage Format 

Message Begin : To start a message on a new line at the left margin, the 
message text must begin with WXbW* (EBCDIC) . CICS/VS recognizes the 
X»17» and changes it to X»25» (XM7» is an idle character). 

Message Body : To write several lines with a single transmission, the 
lines must be separated by X , 1525 l , or if multiple blank lines are 
reguired, by XM52525. . .25* . 

Message End before Next Input : To allow input of the next message on a 
line at the left margin, the preceding message must end with X , 1517 t . 
CICS/VS recognizes X»15' and changes the character following it to 
X»25». 

M essage End before Next Output : In the case of two or more successive 
output messages, the message begin and the message end look the same; 
that is X*'\5'\7 9 , except for the last message (see above). To make the 
message end of the preceding message distinguishable from the message 
begin of the next message, the penultimate character of the message end 
must not be XMS*. 



M essage Lengt h 

It is recommended that messages for teletypewriter terminals, do not 
exceed a length of about 3000 bytes or approximately 300 words. 



CONNECTION THROUGH VTAM 

Both the TWX Model 33/35 Common Carrier Teletypewriter Exchange and the 
WTTY Teletypewriter (World Trade only) can be connected to CICS/VS 
through BTAM, or through VTAM using NTO* 

If a device is connected through VTAM using NTO, the protocols used 
are the same as for the 3767 logical unit, and the application program 
can make use of these protocols. However, the data stream is not 
translated to a 3767 data stream but remains as that for a TWX WTTY. 
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System/3 



i 1 1 1 

III I 

I | DFHTC | TYPE=(READ[,SAVE]) | 



I I I 

) | DFHTC | TYPE= (WRITE[ , WAIT ][ ,SAVE ][ , TRANSPARENT]) 

| | | [ ,DEST= {symbolic address | YES} ] — >TCAM only 

| | | [,ENDMSG=NO] 

I I I 

i 1 1 



| DFHTC | TYPE= {DISCONNECT | RESET} 



| TYPE=DISCONNECT applies to switched line System/3s only. 

System/370 

Support and macro instruction syntax identical to System/3. 
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System/7 



I DFHTC | TYPE=(READ[,WAIT][,SAVE ] 

[ , {TRANSPARENT | PSEUDOBIN} ]) 



DFHTC | TYPE=(WRITE[,WAIT][ ,SAVE] 

[ , {TRANSPARENT |PSEUDOBIN} ]) 

[ ,DEST= {symbolic address | YES} ] — >TCAM only 



CICS/VS treats the System/7 as any other programmable terminal. 
Transactions are normally initiated from the System/7 by issuing a four- 
character transaction code as in the following example : 



SXMIT TRNID 
PBER ERROR 

PLEX 



TRANSMIT TRANSACTION CODE 
BRANCH IF CONDITION ERROR CODE 
WAIT FOR COMPLETION 



TRNID 


#IOLT 


3,CHECK,/0000,TRAN,2 


* 


#IOLT 




* 




3, 


* 






* 




CHECK, 


* 




/OOOO, 


* 




TRAN, 


* 




2 


TRAN 


PEQU 


* 




PDC 


/A6D2 




PDC 


/CAOE 



GENERATE I/O LIST 

RETURN CONTROL ON INTERRUPT 

LEVEL 3 

RETURN CONTROL AT LOCATION CHECK 

TRANSMIT MESSAGE IN BCD MODE 

MESSAGE LOCATED AT TRAN 

MESSAGE TWO WORDS LONG 

TRANSACTION ID 

= «TR* 

= «N7» 



CHECK PEQU 



TEST FOR SUCCESSFUL COMPLETION 



As shown above, the transaction identification is transmitted in BCD 
mode. Pseudo binary mode can be used only while communicating with an 
active CICS/VS transaction; it cannot be used to initiate the 
transaction. Note that the message length is given as the number of 
words to be transmitted (not as the number of characters) . 

When a transaction is initiated on a System/7, CICS/VS services that 
System/7 only for the duration of the transaction; that is, to ensure 
efficient use of the line, any other System/7s on the same line are 
locked out for the duration of the transaction. Therefore, CICS/VS 
application programs for the multipoint System/7 should be designed with 
the shortest possible execution time. 

It is an MSP/7 standard that the first word (two characters) of every 
message received by the System/7 be an identification word. Note, 
however, that all identification words beginning with H a" (X^O 1 ) are 
reserved by CICS/VS for future use. 
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When the PSEODOBIN parameter is specified as part or an input request 
(for example, DFHTC TXPE = (READ, PSEODOBIN) ) , the length of the TIOA 
provided by the application program must be at least twice that of the 
data to be read. If for example, twenty System/7 words (40 bytes) are 
to be read, the data area of the TIOA must be at least 80 bytes in 
length. 

When the PSEODOBIN parameter is specified as part of an output 
request, terminal control always obtains a new TIOA and frees the old 
TIOA unless SAVE is specified. Therefore, on a DFHTC 

TYPE= (WRITE, READ, PSEODOBIN) request, the application program must reload 
the TIOA address (from TCTTEDA) to access the input data from the 
System/7. 

In the case of a System/7 on a dial-Hip (switched) line, the System/7 
application program must, initially, transmit a four-character terminal 
identification. (This terminal identification is generated during 
preparation of the TCT through use of the DFHTCT TYPE=TERMINAL, 
TRMIDNT=parameter specification.) CICS/VS responds with either a 
"ready" message, indicating that the terminal identification is valid 
and that the System/7 may proceed as if it were on a leased line, or an 
INVALID TERMINAL IDENTIFICATION message, indicating that the terminal 
identification sent by the System/7 did not match the TRHIDNT=parameter 
specified. 

Whenever CICS/VS initiates the connection to a dial— up System/7, 
CICS/VS writes a null message, consisting of three idle characters, 
prior to starting the transaction. If there is no program resident in 
the System/7 capable of supporting the Asynchronous Communication 
Control Adapter (ACCA) , BTAM error routines cause a data check message 
to be recorded on the CICS/VS (host) system console . This is normal if 
the task initiated by CICS/VS is to IPL the System/7. Although the data 
check message is printed, CICS/VS ignores the error and continues normal 
processing. If a program capable of supporting the ACCA is resident in 
the System/7 at the time this message is transmitted, no data check 
occurs. 

When a disconnect is issued to a dial— up System/7, the •busy 1 bit is 
sometimes left on in the interrupt status word of the ACCA. If the line 
connection is reestablished by dialing from the System/7 end, the •busy 1 
condition of the ACCA prevents message transmission from the System/7. 
To overcome this problem, the System/7 program must reset the ACCA after 
each disconnect and before message transmission is attempted. This can 
be done by issuing the following instruction: 

PWRI 0,8,3,0 RESET ACCA 

This procedure is not necessary when the line is reconnected by 
CICS/VS (that is, by an automatically initiated transaction). 
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2260 Display Station 



I 

DFHTC | TYPE=({READ|READL}[ , WAIT ][ , SAVE]) 



DPHTC | TYPE= ( {WRITE |WBITEL} [, WAIT ][,SAVE][ , ERASE]) 
| [ , LINEADR= {number | YES} ] 
| [ ,DEST= {symbolic address| YES} ] — >TCAM only 



The following is an example of the coding required to write data to a 
2260 terminal screen and specify the screen line address at which the 
write is to begin: 



DFHTC TYPE=WRITE, 
LINEADR=10 



WRITE DATA TO A TERMINAL SCREEN * 
STARTING AT THIS SCREEN LINE 



The LINEADR operand specifies on which line writing is to begin. The 
hexadecimal equivalent of a line number in the range 1—12 (FO—FB) must 
be provided in the application program. This can be done in either of 
two ways: 

1. By including the LINEADR=number operand in the DFHTC macro 
instruction, as shown above. 

2. By coding a single instruction, prior to issuing the DFHTC macro 
instruction, that places the line number in the TIOALAC field of 
the current TIOA. If the latter method is used, the LINEADR=YES 
operand must be included in the DFHTC macro instruction . 

The following are examples of the coding required to write data to a 
2260 terminal screen and dynamically determine the screen line address 
at which the write is to begin. 
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For Assembler Lanquaqe 


WRITE STARTING AT SCREEN LINE 1 




MVI TIOALAC^'FO 1 




DFHTC TYPE=WRITE, 


WRITE DATA TO 


A TERMINAL SCREEN 


* i 


LINEADR=YES 


STARTING LINE 


ALREADY SPECIFIED 




For COBOL 


NOTE: PLACE STARTING LINE IN TIOA. 




MOVE 2U0 TO TIOALAC. 




DFHTC TYPE=WRITE, 


WRITE DATA TO 


A TERMINAL SCREEN 


* i 


LINEADE=YES 


STARTING LINE 


ALREADY SPECIFIED 




For PL/I 








TIOALAC=240; 


/♦START WRITE 


AT SCREEN LINE 1*/ 




DFHTC TYPE=WRITE, 


WRITE DATA TO 


A TERMINAL SCREEN 


* i 


LINEADR=YES 


STARTING LINE 


ALREADY SPECIFIED 





2265 Display Station 



Support and macro instruction syntax as for 2260 Display Station except 
that the hexadecimal equivalent of a line number can be in the range 1 
through 15 (F0 through FE). 



2740 Communication Terminal 



DFHTC | TYPE=(READ[,WAIT]) 

I 

i 



1 

1 
1 
1 
1 

1 


1 

1 

DFHTC | TYPE=(WRITE[,WAIT][,SAVE]) 

1 [ ,DEST=symbolic address|YES} ]- 

1 

• 


->TCAM only 


■ 
1 
1 
1 

1 

» 
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2741 Communication Terminal 



DFHTC | TYPE=(READ[ ,WAIT]) 

| ,RDATT=symbolic address 

I 

i 



I 

DFHTC | TYPE=(WRITE[ ,WAIT][ ,SAVE]) 

| ,WRBRK=symbolic address 

| [ ,DEST=symbolic address | YES} ] — >TCAM only 



If 2741 read attention support is included by the system programmer at 
system generation, a 2741 terminal operator can signal Read Attention by 
pressing the ATTN key after typing a message. To provide for this, the 
application programmer must issue a 

DFHTC TYPE=READ, * 

RDATT=symbolic address 

macro instruction, where symbolic address is the label of a routine to 
which control is passed if the terminal operator terminates the input by 
pressing the ATTN key. (See "Read Attention" below.) 

If 2741 write break support is included by the system programmer at 
system generation, a 2741 terminal operator can terminate the receipt of 
a message by pressing the ATTN key. To provide for this, the 
application programmer must issue a 

DFHTC TYPE=WRITE, * 

WRBRK=symbolic address 

macro instruction, where symbolic address is the label of a routine to 
which control is passed if the terminal operator presses the ATTN key 
while a message is being received. (Write Break support, described 
below, is not available under CICS/DOS/VS . ) 

Read Attention support may be generated in any CICS/OS/VS or 
CICS/DOS/VS system to permit a response to the terminal operator 
pressing the ATTN key (rather than the return key) after typing a 
message, or without typing a message if no data is to be entered. Write 
Break support may be generated in any CICS/OS/VS system to permit a 
response to the terminal operator pressing the ATTN key while receiving 
a message. The following features must be installed on the 2741: 

• For Read Attention: Transmit Interrupt (7900) . 

• For Write Break: Receive Interrupt (4708). 



Chapter 4.2. Terminal Control (DFHTC Hacro Instruction) 



187 



READ ATTENTION 

If the terminal operator presses the Attention key after typing a 
message, it is recognized as a Read Attention if: 

• Read Attention support is generated into the system (CICS/OS/VS or 
CICS/DOS/VS) . 

• The message is read by a DFHTC TYPE=READ,RDATT=symbolic address 
macro instruction (which has an implied WAIT) . 

When this occurs, control is transferred to a CICS/VS read attention 
exit routine, if it has been generated into the system. This routine is 
a skeleton program that can be tailored by the system programmer to 
carry out actions such as the following: 

• Perform some data analysis or modification on a Read Attention. 

• Return a common response to the terminal operator following a Read 
Attention. 

• Return a response and reguest additional input that can be read 
into the initial input area or into a new area. 

• Reguest new I/O without reguiring a return to the task to reguest 
additional input. 

When the Read Attention exit routine is completed, control is 
returned to the application program at the address specified in the 
DFHTC TIPE=READ macro instruction. The return is made whenever one of 
the following occurs: 

• The exit routine issues no more reguests for input. 

• The exit routine issues a DFHTC TIPE=READ macro instruction and the 
operator terminates the input with a carriage return. (If the 
operator terminates the input with an Attention, the exit routine 
is reentered and is free to issue another READ.) 

If the terminal operator presses the Attention key during a read, it 
is recognised as a read attention only if read attention support is 
generated and if the RDATT operand is included in the DFHTC macro 
instruction reguesting the input. If either or both of these conditions 
do not exist, the "Attention" is treated as a normal read completion, 
that is, as if the return key had been pressed. 



WRITE BREAK (CICS/OS/VS ONLY) 

If the terminal operator presses the Attention key while a message is 
being received, it is recognized as a Write Break if: 

• Write Break support is generated into the system (available only in 
CICS/OS/VS) by the system programmer. 

• The write was initiated by a DFHTC TYPE=WRITE,WRBRK=symbolic 
address macro instruction (which has an implied WAIT) . 

When this occurs, the remaining portion of the message is not sent to 
the terminal. The write is terminated as though it were successful, and 
a new—line character (X"15') is sent to cause a carrier return. Control 
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is returned to the application program at the address specified in the 
DFHTC TYPE=WRITE macro instruction. 

If the Attention key is pressed and the Write Break feature is 
generated in CICS/OS/VS, but the DFHTC TYPE=WRITE macro instruction does 
not have the WRBRK=symbolic address operand, the write break is treated 
as an I/O error. The same is true if the Attention key is pressed, but 
the Write Break feature is not generated in CICS/OS/VS. A write can be 
interrupted only if both conditions identified above are satisfied. 

Note : TYPE=WAIT and/or SAVE can be coded with READ and/or WRITE, but 
only RDATT or WRBRK (not both) can be specified in one DFHTC macro 
instruction. 
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2770 Data Communication System 

Support and macro instruction syntax identical to System/3. The 2770 
Data Communication System recognizes a read interrupt and responds by 
transmitting the contents of the I/O buffer. After the contents of the 
buffer have been transmitted, the 2770 responds to the next read 
continue with an EOT. If the I/O buffer is empty, the 2770 transmits an 
EOT. CICS/VS issues a read interrupt and read continue to relinquish 
use of the line and to enable the application program to write to the 
2770. 

Input from a 2770 consists of one or more logical records. CICS/VS 
provides one logical record for each read request to the application 
program. Note that the size of a logical record cannot exceed the size 
of the I/O buffer. If the input spans multiple buffers, multiple reads 
must be issued by the application program. 

The 2265 component of the 2770 Data Communication System is 
controlled by data stream characters, not BTAM macro instructions. 
Therefore, the user should provide the appropriate screen control 
characters in the TIOA. 

For 2770 input, data is deblocked to ETX, ETB, RS, and OS characters. 
These characters are moved with the data to the TIOA but are not 
included in the data length (TIOATDL) . The application programmer 
should be aware that such characters as NL, CR, and LP are passed in the 
TIOA as data. 



2780 Data Transmission Terminal 

Support and macro instruction syntax identical to System/3. The 2780 
Data Transmission Terminal recognizes a read interrupt and responds by 
transmitting the contents of the I/O buffer. After the contents of the 
buffer have been transmitted, the 2780 responds to the next read 
continue with an EOT. If the I/O buffer is empty, the 2780 transmits an 
EOT. CICS/VS issues a read interrupt and read continue to relinquish 
use of the line and to enable the application program to write to the 
2780. 

Input from a 2780 consists of one or more logical records. CICS/VS 
provides one logical record for each read request to the application 
program. Note that the size of a logical record cannot exceed the size 
of the I/O buffer. If the input spans multiple buffers, multiple reads 
must be issued by the application program. 

Output to a 2780 requires that the application programmer insert the 
appropriate "escape seguence" for component selection associated with 
the output message. (For programming details, see the publication 
Component Description : IBM 2780 Data Transmission Terminal . ) 

For 2780 input, data is deblocked to ETX, ETB, RS, and US characters. 
These characters are moved with the data to the TIOA but are not 
included in the data length (TIOATDL) . The application programmer 
should be aware that such characters as NL, CR, and LF are passed in the 
TIOA as data. 
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2980 General Banking Terminal 



DFHTC | TYPE=(READ[, WAIT ][, SAVE]) 

I 

i 



I I 

DFHTC | TYPE={CBUFF|PASSBK} I 

| [ ,DEST= {symbolic address| YES} ] — >TCAM only | 



PASSBOOK CONTROL 

Two one-byte fields of the terminal control table terminal entry (TCTTE) 
may be interrogated by an application program servicing passbook 
requests from the 2980. These fields are: 

• TCTTETAB, which contains the binary representation of the number of 
tabs necessary to position the print element to the correct 
passbook area. 

• TCTTEPCF, which contains the indicators (flags) necessary for 
passbook control operations. The indicators TCTTEPCR and TCTTEPCW 
indicate whether or not the passbook is present on a read or a 
write operation, respectively. The same indicators are used to 
show the presence of the Auditor key on the 2980 Model 2. 

By testing indicators TCTTEPCR and TCTTEPCW, the application program 
can maintain positive control with regard to the absence or presence of 
a passbook during an update operation. Care must, however, be taken not 
to alter these indicators, otherwise unpredictable results may occur. 

If the passbook is present on a read (entry) operation, the TCTTEPCR 
indicator is turned on (set to a binary one) by CICS/VS. In this case, 
the application program generally issues a write operation back to the 
passbook area to update the passbook. After the write operation, the 
application program must check the TCTTEPCW indicator to ensure that the 
passbook was present at the time the write occurred. If the TCTTEPCW 
indicator is off (set to a binary zero) , the passbook was not present 
and the write operation did not occur. The data sent to the terminal 
(and not printed because of the "no passbook" condition) is, however, 
returned to the application program in its original form for subsequent 
retransmission . 

When the "no passbook" condition occurs on a write, CICS/VS allows an 
immediate write to the terminal. The application program should write 
an error message to the journal area of the terminal to inform the 2980 
operator of this error condition. To allow the operator to insert the 
required passbook, CICS/VS automatically causes the transaction to wait 
23.5 seconds before continuing. 

After regaining control from CICS/VS following the writing of the 
error message, the application program can attempt another write to the 
passbook area when it has ensured that the print element is positioned 
correctly in the passbook area. This is generally accomplished by 
issuing two carrier returns followed by the number of tabs required to 
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move the print element to the correct position. (The correct number of 
tabs can be acquired from TCTTETAB.) 

If the TCTTEPCW indicator is off following the second attempt to 
write to the passbook area, the application program can send another 
error message or take some alternative action (for example, place the 
terminal "out of service"). 

In summary, all writes to the passbook area are conditional on a 
passbook being present before a write can be executed successfully. 
Therefore, a read operation cannot be combined with a passbook write. 
For example, a DFHTC TYPE= (WRITE, READ, WAIT) macro instruction is an 
invalid request for 2980 terminal services involving the passbook area. 
A DFHTC TYPE=PASSBK macro instruction is permissible because it implies 
only WRITE, WAIT. 

Note ; The application programmer should not insert shift characters in 
output data, because this is done automatically by CICS/VS. CICS/VS 
removes shift characters from input data. 



SEGMENTED WRITES CONTROL 

Segmented writes are supported for both the journal area and the 
passbook area. Journal area segmented writes are limited in length by 
the hexadecimal half word value that the user stores in TIOATDL. 
Passbook segmented writes are limited to a one— line logical write to 
ensure positive control when spacing (indexing) past the bottom of the 
passbook. 

For example, consider a 2972 buffer length of 48 and a 2980 Model 4 
logical write (print) area of 100 characters per line. The application 
program can write a logical record (DFHTC TYPE=PASSBK) of 100 characters 
to this area; CICS/VS automatically segments the record to adjust to the 
buffer size. The application program must insert the passbook indexing 
character (X'25 1 ) as the last character written in one logical write to 
the passbook area. This is done to control passbook indexing and 
thereby achieve positive control of passbook presence. 

If the message contains embedded passbook index characters and 
segmentation is necessary because of the logical length of the message, 
the write terminates if the passbook spaces beyond the bottom of the 
passbook; the remaining segments are not printed. 
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DATA HANDLING 

SHIFT CHARACTERS: Shift characters are handled by the terminal control 
program and are of no concern to the application programmer. They are 
stripped from input messages and added to output messages as required. 
Data can be written in any mix of uppercase, lowercase, or special 
characters. (See the 2980 Translate Tables in Appendix D.) 

JOURNAL INDEXING: Journal indexing is the responsibility of the 
application programmer. Carriage returns (XM5') may be inserted 
anywhere in the logical message. For futher information, see the 
appropriate SNA Guide. 

PASSBOOK INDEXING: Passbook indexing necessitates special consideration 
by the application programmer to control bottom— line printing on the 
passbook. (See "Passbook Control" and "Segmented Writes Control"; the 
two preceding sections.) 

TAB CHARACTERS: The tab character (X'OS 1 ) is controlled by the 
application programmer. As stated above, the number of tabs required to 
position the print element to the first position of the passbook is 
available at TCTTETAB. This value is specified by the system programmer 
when generating the terminal control table and may be unique to each 
terminal. Other tab characters are inserted as needed to control output 
format. 

MISCELLANEOUS CHARACTERS: Turn page, message light, openchute, and 
special banking characters can be used by the application programmer as 
needed. (See the 2980 Translate Tables in Appendix D.) 

AUDITOR KEY MODEL 2: Presence of the Auditor key is controlled through 
use of the DFHTC TYPE=PASSBK macro instruction and may be used in a 
manner similar to that for passbook control. (See "Passbook Control", 
earlier in this Chapter.) 

2980 MODEL NUMBER: TCTTETM contains the 2980 model number expressed as 
a hexadecimal value (X , 1», X , 02 t , X^OU 1 ). Since CICS/VS uses the model 
number to select the correct translate table for each of the 2980 
models, the application program should not alter this field. 

COMMON BUFFER: Common buffer writes (DFHTC TYPE=CBUFF) are translated 
to the receiving TCTTE model character set. If more than one 2980 model 
type is connected to the 2972 Control Unit, the lengths are 
automatically truncated if they exceed the buffer size. 
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For COBOL 



DATA DIVISION 

WORKING STORAGE SECTION 

01 DFH2980 COPY DFH2980, 



LINKAGE SECTION. 

01 DFHBLLDS COPY DFHBLLDS. 

02 TCTTEAR PIC S9 (8) COMP, 
02 TIOABAR PIC S9(8) COMP. 



01 DFHTCTTE COPY DFHTCTTE. 
01 DFHTIOA COPY DFHTIOA. 
02 DATA PIC X (20) . 
02 FILLER REDEFINES DATA. 
03 TAB1-1 PIC X. 
03 DATA1 PIC X(19). 
02 FILLER REDEFINES DATA. 
03 TAB1-2 PIC X. 
03 TAB2-2 PIC X. 
03 DATA2 PIC X(18) . 



PROCEDURE DIVISION. 



IF TCTTETAB = TAB-ONE GO TO ONETBCH 
IF TCTTETAB = TAB-TWO GO TO TWOTBCH 



ONETBCH. 

MOVE TABCHAR TO TAB1-1 . 
MOVE TOTAL TO DATA1. 



TWOTBCH. 

MOVE TABCHAR TO TAB1-2, TAB2-2 
MOVE TOTAL TO DATA2. 
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For PL/I; 



^INCLUDE DFHTIOA; 

2 DATA CHAR (20) ; 

DECLARE 1 USERTI0A_1 BASED 
2 TIOAFILL CHAR (12) , 
2 TAB1_1 CHAR (1) , 
2 DATA1 CHAR (19) , 

DECLARE 1 USERTIOA_2 BASED 
2 TIOAFILL CHAR (12), 
2 TAB1_2 CHAR (1) , 
2 TAB2_2 CHAR (1) , 
2 DATA2 CHAR (18) ; 



96INCLUDE DFH2980; 



(TIOABAR) , 



(TIOABAR) , 



IF (TCTTETAB = TAB_ONE) THEN GO TO ONETCBH; 
IF (TCTTETAB = TAB_TWO) THEN GO TO TWOTBCH; 



ONETBCH: TAB1_1 = TABCHAR; 
DATA1 = AMOUNT; 



TWOTBCH: TAB1_2 = TABCHAR; 
TAB2_2 = TABCHAR; 
DATA2 = AMOUNT; 



In the COBOL example, the structure DFH2980 is copied in the Working 
Storage Section; in the PL/I example, DFH2980 is included following the 
XINCLUDE statements for the based structures. DFH2980 contains 
constants that may be used when writing application programs for the 
2980. 

The application program is also expected to test the TCTTEPCF field 
to determine whether a passbook was present on a read or write. 
TCTTEPCR and TCTTEPCW are located in DFH2980 to aid in this testing. 

To test the TCTTEPCF field in COBOL, statements such as the following 
might be used: 

MOVE TCTTEPCF TO HOLDPCF. 

IF HOLDPCFB = (HOLDPCFB / TCTTEPCW) * TCTTEPCW 

THEN GO TO BOOK-FOR-PRESENT-WRITE . 

Substituting TCTTEPCR for TCTTEPCW allows the COBOL programmer to 
test for the presence of a passbook on a read. (HOLDPCF and HOLDPCFB 
are also part of DFH2980.) 

To test the TCTTEPCF field in PL/I, statements such as the following 
might be used: 
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IF (TCTTEPCP | TCTTEPCW) THEN GO TO 
BOOK_PRESENT_WRITE ; 

Substituting TCTTEPCR for TCTTEPCW allows the PL/I programmer to test 
for the presence of a passbook on a read. 

To test the station identification and to determine whether the 
normal station or alternate station is being used, values of the forms 
shown below are predefined in DFH2980: 

STATION-#-A OR STATION-#-N (for COBOL) 

STATION_#_A OR STATION_#_N (for PL/I) 

where # is an integer (0 through 9) and A and N signify alternate and 
normal stations. The values are one— byte character values and can be 
compared to TCTTESID in an IF statement. 

To test the teller identification on a 2980 Model 4, the TCTTETID 
field is defined as a one— byte character value. It can be tested in an 
IF statement. 

Thirty special characters are defined in DFH2980. Twenty— three of 
these can be referred to by the name SPECCHAR-X or SPECCHAR__X (for COBOL 
or PL/I) where X is an integer (0 through 23) . The seven other 
characters are defined with names that imply their usage, for example, 
TABCHAR. For further information on these thirty characters, see 
Appendix D. 

The names defined in DFH2980 for COBOL follow: 



STATI0N-0-N 


STATION-6- 


-A 


TAB-SIX 




MSGLITE 


SPECCHAR- 


-11 


STATI0N-0-A 


STATION-7- 


-N 


TAB-SEVEN 




BCKSPACE 


SPECCHAR- 


-12 


STATI0N-1-N 


STATION-7- 


-A 


TAB-EIGHT 




TRNPGE 


SPECCHAR- 


-13 


STATI0N-1-A 


STATION-8- 


-N 


TAB-NINE 




SPECCHAR-1 


SPECCHAT- 


-14 


STATI0N-2-N 


STATION-8- 


-A 


HOLDPCFB 




SPECCHAR-2 


SPECCHAR- 


-15 


STATI0N-2-A 


STATION-9- 


-N 


DFHFILL 




SPECCHAR-3 


SPECCHAR- 


-16 


STATI0N-3-N 


STATION-9- 


-A 


HOLDPCF 




SPECCHAR -4 


SPECCHAR- 


-17 


STATI0N-3-A 


TAB-ZERO 




TCTTEPCR 




SPECCHAR-5 


SPECCHAR- 


-18 


STATI0N-4-N 


TAB-ONE 




TCTTEPCW 




SPECCHAR -6 


SPECCHAR- 


-19 


STATI0N-4-A 


TAB-TWO 




TABCHAR 




SPECCHAR-7 


SPECCHAR- 


-20 


STATI0N-5-N 


TAB-THREE 




OPENCH 




SPECCHAR-8 


SPECCHAR- 


-21 


STATI0N-5-A 


TAB-FOUR 




JRNLCR 




SPECCHAR-9 


SPECCHAR- 


-22 


STATI0N-6-N 


TAB-FIVE 




PSBKCR 




SPECCHAR-1 


SPECCHAR- 


-23 


The names def 


ined in DFH2980 


for PL/I follow: 






STATION N 


STATION 7 


A 


TCCTEPCR 




SPECCHAR_7 


SPECCHAR. 


22 


STATION_0_A 


STATION_8~ 


_N 


TCTTEPCW 




SPECCHAR_8 


SPECCHAR] 


J23 


STATION 1 N 


STATION 8~ 


A 


TABCHAR 




SPECCHAR 9 






STATION 1 A 


STATION 9 


"n 


OPENCH 




SPECCHAR_10 






STATION 2 N 


STATION 9~ 


"a 


JRNLCR 




SPECCHAR 11 






STATION 2_A 


TAB ZERO 




PSBKCR 




SPECCHAR 12 






STATION 3 N 


TAB ONE 




MSGLITE 




SPECCHAR 13 






STATI0N_3_A 


TAB_TWO 




BCKSPACE 




SPECCHAR_14 






STATION 4 N 


TAB THREE 




TRNPGE 




SPECCHAR_15 






STATION 4 A 


TAB FOUR 




SPECCHAR 


1 


SPECCHAR_16 






STATI0N_5_N 


TAB-FIVE 




SPECCHAR_ 


2 


SPECCHAR_17 






STATI0N_5_A 


TAB SIX 




SPECCHAR 


3 


SPECCHAR_18 






STATION 6 N 


TAB_SEVEN 




SPECCHAR" 


'u 


SPECCHAR 19 






STATI0N_6_A 


TAB_EIGHT 




SPECCHAR" 


"5 


SPECCHAR_20 






STATION 7 N 


TAB NINE 




SPECCHAR" 


6 


SPECCHAR 21 
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3270 Information Display System (BTAM and TCAM) 



I 

DFHTC | TYPE= ({READ | READB} [ ,WAIT][ , SAVE ][ , TEXT]) 

I 

| READB not available under TCAM 




TYPE= ( {WRITE | COPY | PRINT | ERASEAOP} 

[ ,WAIT][ , SAVE ][, ERASE], [STRFIELD]) 
[ ,CTLCHAR= {hexadecimal number | YES} ] 
[,DEST= {symbolic address | YES} ] — >TCAM only 

COPY and PRINT not available under TCAM 



When input is to be received from a terminal of the 3270 Information 
Display System, the application programmer can use 



or 



DFHTC TYPE= (READ, TEXT) 

DFHTC TYPE=TEXT 
DFHTC TYPE=READ 
DFHTC TYPE=WAIT 



to request a temporary override of the uppercase translation features of 
CICS/VS, thus allowing a message containing both uppercase and lowercase 
data to be received from a terminal. 

If the 3270 print request facility was included in the terminal 
control program at CICS/VS system initialization, the application 
program can issue a DFHTC TYPE=PRINT macro instruction to cause the data 
currently displayed on a 3270 display to be printed on the first 
available eligible 3270 printer. 

For a printer to be available for printing from a display, it must be 
in service and not currently attached to a task. For it to be eligible, 
it must be attached to the same control unit as the display, must have a 
buffer capacity egual to or greater than that of the display, and must 
have had FEATURE=PRINT specified for it in the TCT by the system 
programmer. 

If the 3270 display is a 3275 with an attached printer, and 
FEAT0RE=PRTADAPT has been specified in the TCTTE; the data will be 
printed on the attached printer. 

Some 3270 displays have the facility to copy a screen image to a 
printer that is attached to the same control unit, without host 
intervention. This is a hardware facility, and is not under the control 
of CICS/VS. For further details see "printer authorization matrix", IBM 
3270 Information Display System Component Description . 

For those devices with switchable screen sizes, the size of the 
screen that can be used and the size to be used for a particular 
transaction are defined at CICS/VS system generation. These values are 
available to the application programmer in fields in the TCTTE. These 
fields are listed in Appendix C. 
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3270 Logical Unit 



I I 

I DFHTC | TYPE= ( {READ |READB> [, WAIT ][, SAVE ][, TEXT]) 
[ ,EOC=symbolic address] 



I 




TYPE= ( {WRITE | PRINT | COPY | ERASEAUP ] 

[ , WAIT ][, SAVE ][ ,ERASE],[STRFIELD]) 

[ ,CTLCHAR= {hexadecimal number | YES) ] 

[,CCOMPL=NO] 

[ ,DEFRESP=YBS] 

[ ,DEST= {symbolic address | YES) ] — >TCAM only 



In general, programming for a 3270 logical unit is the same as 
programming for a 3270 via BTAM, that is, the COPY, PRINT, READB, ERASE, 
| and ERASEAUP are supported as before. The additional operand (DEFRESP) 
| has been added to the DFHTC terminal control macro instruction, and 
there are some restrictions: 

• 2260 Compatibility is not supported. 

• ASCII code is not supported (but, for BSC 3270, code translation 
can be carried out by NCP translation tables in the 3704/3705 
communications controller) . 

• DFHTC TYPE=C0PY must specify a symbolic terminal identification; a 
physical device address cannot be specified. 

If the 3270 print request facility is included at system 
initialization, the DFHTC TYPE=PRINT macro will enable the data 
displayed on the screen to be printed on the first available printer 
that is eligible. 

An available printer is one that is in service and that is not 
attached to a task . 

| An eligible printer is one for which the PRINTTO or ALTPRT option has 
been specified in the TCT. 

If COPY has also been specified with these options, the printer must 
| be attached to the same 3270 control unit as that used for the display . 

If an eligible printer is unavailable, the data in the display buffer 
is captured, a message is sent to the master terminal operator by the 
terminal abnormal or node abnormal condition program PFHZNAC) and 
control is passed to a user— written terminal or node error program which 
provides an appropriate action, for example, if the printer is already 
attached to a task, the user-written error program can direct the data 
to another printer or hold the data until the busy printer becomes 
available . 

If the 3270 display is a 3275 with an attached printer, and 
FEATURE=PRTADAPT has been specified in the TCTTE; the data will be 
printed on the attached printer. 

Some 3270 displays have the facility to copy a screen image to a 
printer that is attached to the same control unit, without host 
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intervention. This is a hardware facility, and is not under the control 
of CICS/VS- For further details see "printer authorization matrix", IBM 
3270 Inforaation Display System Component Description . 

For those devices with switchable screen sizes, the size of the 
screen that can be used and the size to be used for a particular 
transaction are defined at CICS/VS system generation. These values are 
available to the application programmer in fields in the TCTTB. These 
fields are listed in Appendix C. 
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3270 LUTYPE2 Logical Unit 



I 

DFHTC | TYPE= ({READ | READB) [ ,WAIT ][ , SAVE ][ , TEXT]) 
|| | | [ ,EOC=symbolic address] 



I I 

I 

I I 



I 



I 



DFHTC | TYPE=( {WRITE | PRINT |ERASEAUP) 

I [,WAIT][ ,SAVE][, ERASE ][,STRFIELD]) 

[ ,CTLCHAR = {hexadecimal number |YES) ] 
[,CCOMPL=NO] 
[ ,DEFRESP=YES] 
[ ,DEST= {symbolic address | YES) ] — >TCAM 



I 



only 



I 

DFHTC | TYPE=SIGNAL 



I 



{,SIGADDR=symbolic address | ,WAIT=YES) 



Logical unit type 2 (LUTYPE2) is a logical unit defined by SNA, and 
which accepts a 3270 display data stream. 

Support and macro syntax are the same as for the 32 70 logical unit 
except that TYPE=COPY is not supported. 

Some 3270 displays have the facility to copy a screen image to a 
printer that is attached to the same control unit, without host 
intervention. This is a hardware facility, and is not under the control 
of CICS/VS. For further details see "printer authorization matrix", in 
the IBM 3270 Information Display System Component Description . 

For those devices with switchable screen sizes, the size of the 
screen that can be used and the size to be used for a particular 
transaction are defined at CICS/VS system generation. These values are 
available to the application programmer in fields in the TCTTE . These 
fields are listed in Appendix C. 
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3270 LUTYPE3 Logical Unit 



TTPE= ({WRITE | PRINT | ERASEAUP} 

[,WAIT][ ,SAVE][,ERASE][,STRPIELD]) 

[ ,CTLCHAR = (hexadecimal number | YES} ] 

[,CCOMPL=NO] 

[ ,DEPRESP=YES] 

[ ,DEST= {symbolic address | YES} ] — >TCAM only 




I 

| DPHTC 



TYPE=SIGNAL 

(,SIGADDR=symbolic address |,WAIT=YES} 



Logical unit type 3 (LUTYPE3) is a logical unit defined by SNA, and 
which accepts a 3270 display data stream. 

Support and macro syntax are the same as for the 3270 logical unit 
| except that TYPE=RBAD, READB and COPY are not supported, but 
| TYPE=WRITE,WAIT,READ is supported for STRPIELD to issue QUERY. 
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3270 SCSPRT Logical Unit 




TYPE= (WRITE[ ,WAIT][ , SAVE ][ ,LAST ]) 
[,CCOMPL=NO] 
[,DEFRESP=YES] 
[ ,DEST= {symbolic address | YES} ] — >TCAH only 



I I 



I I 

| DFHTC | TYPE=(READ[,WAIT][ ,SAVE]) 
| | [ ,EOC=symbolic address] 



I 



I 



| DFHTC | TYPE=SIGNAL 



I 



{,SIGADDR=symbolic address |,WAIT=YES} 



The SCS printer logical unit (SCSPRT) accepts an SCS data stream. SCS 
is defined by SNA. Certain devices connected as SCSPRT have input 
capability (for example, PA keys on 3287), in which case TYPE=SIGNAL 
should be used to detect operator input, followed by TYPE=READ to obtain 
the input. Alternatively, TYPE= (READ, WAIT) can be issued alone, in 
which case the program will wait for operator input. 
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3270 in 2260 Compatibility Mode (BTAM only) 



•i 1 1 

I I I 

I DFHTC | TYPE= ( {READ |READL}[,W AIT ][ , SAVE ][, TEXT ]) | 



I I 

| DFHTC | TYPE= ({WRITE | WRITEL} , WAIT ][SAVE][, ERASE]) 

| j [ ,CTLCHAR= {hexadecimal number | YES}] 

| | [ ,LINEADR= {number | YES} ] 

| | [ ,DEST= {symbolic address | YES} ] — >TCAM only 



If required, the 3270 may be used in 2260 compatibility mode. This 
means that a 3270 terminal is used in place of a 2260 terminal but uses 
2260— based transactions developed for earlier versions of CICS/VS. To 
make this support available, the system programmer must, during system 
generation, have requested that 2260 compatibility be included in the 
CICS/VS system. This generates the code necessary to convert 2260 data 
streams from user— written application programs to the appropriate 3270 
data stream format, or 3270 to 2260. 2260— compatibility support is not 
available for a 3270 connected to CICS/VS via VTAM (3270 logical unit or 
3650 host— conversational (3270) logical unit). 

When a write to a 3270 terminal (operating in 2260 compatibility 
mode) is specified, that is, by issuing the 

DFHTC TYPE= (WRITE, ERASE) 

macro instruction, the screen is erased and the cursor is returned to 
the upper left corner of the screen before writing starts. If the ERASE 
parameter is omitted, writing begins wherever the cursor is located at 
the time the write is issued. 

To simply erase the screen, the application programmer can 

1. Place at TCTTEDA the address of a TIOA. 

2. Place at TIOATDL a data length of 0. 

3. Issue a DFHTC TYPE= (WRITE, ERASE) macro instruction. If operating 
in 2260 compatibility mode, the TIOA" should only contain a start 
symbol. Set the data length in TIOATDL to 1 before issuing the 
DFHTC TYPE= (WRITE, ERASE) . 

The following example shows how to write data to a 3270 terminal 
operating in 2260 compatibility mode, and how to specify the screen line 
address at which the write is to begin: 

DFHTC TYPE=WRITE, WRITE DATA TO A TERMINAL SCREEN * 

LINEADR=10 STARTING AT THIS SCREEN LINE 

The following examples show how to write data to a 3270 terminal 
operating in 2260 compatibility mode, beginning at a screen line address 
placed in TIOALAC prior to issuing the write request. 
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1 

1 For Assembler Lancruacre: 










| MVI TIOALAC,X»F0» 


WRITE STARTING AT SCREEN LINE 1 






| • 

| • 

| DFHTC TYPE=WRITE, 
| LINEADR=YES 


WRITE DATA TO 
STARTING LINE 


A TERMINAL SCREEN 
ALREADY SPECIFIED 


♦ 




1 For COBOL: 










| HOVE 240 TO TIOALAC. 

1 • 


NOTE PLACE STARTING LINE IN TIOA. 






1 • 
1 * 

| DFHTC TYPE=WRITE, 
| LINEADR=YES 


WRITE DATA TO 
STARTING LINE 


A TERMINAL SCREEN 
ALREADY SPECIFIED 


* 




1 For PL/I: 










| TIOALAC=240? 

1 • 


/*START WRITE 


AT SCREEN LINE 1*/ 






1 • 
f • 

| DFHTC TYPE=WRITE, 
| LINEADR=YES 


WRITE DATA TO 
STARTING LINE 


A TERMINAL SCREEN 
ALREADY SPECIFIED 


♦ 
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3600 Finance Communication System (BTAM) 



I I 

I DFHTC | TYPE=(READ[ , WAIT ][ , SAVE]) 

I I 

.1 I 



•| 1 

I I 

| DFHTC | TYPE=(WRITE[,WAIT][ , SAVE ][, TRANSPARENT ]) 

I I 



INPUT 

The unit of transmission from a 3601 to CICS/VS is a segment consisting 
of data link control characters, the one— byte identification of the 3600 
logical unit that issued the CPU write, and the data written. The units 
received can be in the following forms : 



r™ ■■" 




■ 


I s 




E I 


I T 


id data 


T | 


I x 




B I 



or 



1 






i 


1 s 




E 


1 


1 T 


id data 


T 


1 


1 x 




X 


1 


i. 






-1 



where STX means "start of text", ETB means "end of block" and ETX means 
"end of text". 

A logical unit sends a message either in one segment, as follows: 



I S 
I T 
I X 



id data 



1 

E I 
T | 
X I 



or in more than one segment, as follows: 



1 




" i 


i 




_ .<„ t 


i 




— i 


1 s 




B 1 


1 s 




E I 


1 s 




E I 


1 T 


id data 


T | 


1 T 


id data 


T | . 


-- 1 T 


id data 


T I 


1 x 




B I 


1 x 




B I 


1 x 




X I 


> 




i 


L 




i 


i 




• 



The input TIOA passed to the user— written application program 
consists of the data only. The one— byte field TCTTEDLM contains flags 
describing the data— link control character (ETB, ETX, or IRS) that ended 
the segment. The application program can issue terminal control macro 
instructions to read the data until it receives a segment ending with 
ETX. If blocked data is transmitted it is received by CICS/VS as 
follows: 



r~~~ 
I S 
I T 
I X 

i 



id1 data | 
I 



I 

| id2 data 

I 



1 — 

1 




i 

E I 


1 
1 


idn data 


T | 
X I 


1 




• 
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For blocked input, the flags in TCTTEDLM only indicate end of 
segment, not end of message. The CICS/VS application program still 
receives only the data, but user— defined conventions may be required to 
determine the end of the message. 

The field TCTTEDLM also indicates the mode of the input, either 
transparent or non— transparent. Blocked input is n on— transparent. 

The terminal control program does not pass input containing a "start 
of header" (SOH) data link control character to a user— written 
application program. If it receives an SOH it sets an indicator in 
TCTTEDLM, passes the input to the user exit in the terminal control 
program, and then discards it. 



OUTPUT 



When an application program issues a terminal control write, the 
terminal control program determines, from the value specified in the 
BUFFER parameter of the DFHTCT TYPE=TERMINAL system macro, the number of 
segments to be built for the message. It sends the message to the 3600 
logical unit in one segment, as follows: 



I S 
I T 
I X 
i 



data 



E I 
T I 
X I 



or in multiple segments, as follows: 



data 



E I 
T | 

B I 
1 



I s 
I T 
I X 



data 



E I 
T | 
B I 



I s 




i 
E I 


1 T 


data 


T I 


1 x 

i 




X I 

■ 



The host input buffer of the 3600 controller and the input segment of 
the receiving logical unit must be large enough to accommodate the data 
sent by CICS/VS. However, space for the data link control characters 
need not be included. The 3600 application program reads the data from 
the host, by means of an LREAD, until it has received the entire 
message . 

The terminal control program sends data in transparent mode when the 
user— written application program issues a DFHTC TYPE=TRANSPARENT macro. 
Otherwise, data is sent in non— transparent mode. 

CICS/VS system output messages begin with "DFH" followed by a four- 
byte message number and the message text. These messages are sent in 
non— transparent mode. It is suggested that CICS/VS user— written 
application programs do not send messages starting with "DFH" to the 
3601. 
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RESEND MESSAGE 

When a logical unit sends a message to the host and a short— on— storage 
condition exists or the input is unsolicited (the active task associated 
with the terminal has not issued a read) , the terminal control program 
sends a "resend" message to the logical unit. The format of this 
message is DFH1033 RE-ENTEB followed by XM5' (a 3600 new line 
character) followed by the first eight bytes of the text of the message 
being rejected. No message is sent to the destinations CSMT or CSTL. 

The first eight bytes of data sent to CICS/VS can be used by the 3600 
application program to define a convention to associate responses 
received from CICS/VS with transactions sent to the host, for example, 
sequence numbers could be used. 

If a CICS/VS user— written application program has already issued a 
terminal control write when a resend situation occurs, the resend 
message is not sent to the 3601 until the user— written application 
program message has been sent. A 3600 logical unit cannot receive a 
resend message while receiving a segmented message. 

Only one resend message at a time can be queued for a logical unit. 
If a second resend situation occurs before CICS/VS has written the 
first, a resend message, containing the eight bytes of data that 
accompanied the second input transaction from the 3 600 logical unit, is 
sent. 

The resend message is sent in transparent mode if the input data from 
the 3601 to be re— transmitted is received by CICS/VS in transparent 
mode. Otherwise it is sent in non— transparent mode. 
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3600 (3601) Logical Unit 



I I 



I 



I 



I DFHTC | TYPE=(RBAD[,WAIT][,SAVE]) 

| | [ ,EOC=symbolic address] 

| | [ r IHBFHH=symbolic address] 



I I 



I 



I 



| DFHTC | TYPE=(WRITE[, WAIT ][ SAVE ][ LAST]) 

I | [ ,LDC= {mnemonic | YES) ] 

| | [,FMH={NO|YES) ] 

| | [,CCOMPL=HO] 

| | [ ,DEFRESP=YES] 

| | [, DBST= {symbolic address | YES) ] — >TCAM 



only 



1 1 


1 

■ 


1 




1 r 


i 


I 



I 



I 



I DFHTC | TYPE=SIGNAL 



I 



I 



{,SI6ADDB=symbolic address | ,WAIT=YES) 



3600 Pipeline Logical Unit 




3600 (3614) Logical Unit 



I I I 

I | | DFHTC | TYPE=(READ[ ,H AIT ][ , SAVE]) 

I I I 

i i i 



I I I 

| | | DFHTC | TYPE=(WRITE[ ,iAIT][ ,SAVE ]) 

I I I 

i 1 1 
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3630 Plant Communication System 



The 3630 Plant Communication System is supported as a 3600. Two types 
of logical unit can be defined for a 3630: the 3600 (3601) logical unit 
and the 3600 pipeline logical unit. The macro instruction syntax is as 
shown above for these logical units. 



3650 Host Command Processor Logical Unit 



I I 



DFHTC 



TYPE = (READ[ ,WAIT ][ ,SAVE ]) 

[ , E0C=sy mbolic address ] 




I 

DPHTC | TYPE=(WRITE[ , WAIT ][ , SAVE]) 
| [,FMH=YES] 

| [,CCOMPL=NO] 



3650 Host Conversational (3270) Logical Unit 



I I 



I I 

I DFHTC | 



TYPE= (BEAD[ ,WAIT ][ ,SAVE ]) 

[ ,EOC=sy mbolic address] 




TYPE= ( {WRITE | PRINT | ER ASEAUP) 

[ ,WAIT][,SAVE][ , ERASE ][ ,LAST]) 

[ ,CTLCHAR= {hexadecimal number | YES) ] 

[,CCOMPL=NO] 

[ ,DEFRESP=YES] 

[,FMH=YES] 



00TP0T DEVICE CONTROL 



Device control characters for 3650 devices can be inserted by CICS/VS 
application programs into output data streams. To avoid designing such 
device— dependent CICS/VS application programs, device responsibility can 
be moved to the 3650 application programs. Thus, the CICS/VS 
application programs would be concerned with data content, while data 
format would be the responsibility of the 3650 application program. 

Another alternative is available for handling device-dependent 
matters. Basic mapping support (BMS) can be used to write data to 
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logical units (except for pipeline) . BBS can be used to format data and 
insert the necessary 3650 device control characters. 



THE ERASE FUNCTION 



The erase option is supported by the DPHTC macro instruction when this 
macro is issued for a host conversational (3270) logical unit. The 
erase function for this logical unit is controlled as a device-dependent 
character. The erase function can be obtained using BUS. 



3650 Pipeline Logical Unit 




3650 Host Conversational (3653) Logical Unit 



I I I 

I | | DPHTC | TYPE=(READ[ ,WAIT][ , SAVE ]) 

|| | [ ,EQC=symbolic address] 

I I I 

i i i 



I I I 

| | | DFHTC | TYPE= (WRITE[ , WAIT ][ , SAVE ][ , LAST]) 

|| | [ ,CCOMPL=NO ] 

| | | [,DEPRESP=YES] 

I I I 
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3650 Interpreter Logical Unit 




TYPE=PROGRAM 

,PRGNAME=name 
[ ,VALID=address] 
[ ,NONVAL=address] 
[ ,CONNECT= {ACTIVATE | CONVERSE) ] 
[ ,NORESP=address] 




TYPE= (READ[ ,WAIT ][ , SAVE ]) 

[ ,EODS=symbolic address] 
[ ,EOC=symbolic address] 
[ ,INBFMH=symbolic address] 



I I 

| DFHTC | 

I I 



TYPE= (WRITE[ # HAIT ][ ,SAVE ][ ,LAST ]) 
[ ,FMH={YES|NO) 
[ # DEFRESP=YES] 



I I 

| DFHTC | TYPE=EODS — >VTAM only 

I I 



3660 Supermarket Scanning System (BTAM) 



Support and macro instruction syntax identical to System/3, except that 
the 3660 cannot initiate communications; the host system initiates all 
transactions. 
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3735 Programmable Buffered Terminal 



I I I 

I DFHTC | TYPE= (READ[ , WAIT ][ , SAVE]) | 

| | [ ,EOF=symbolic address] j 

I I I 

-i i i 



III I 

| | DFHTC | TIPE=(WRITE[ ,WAIT][ ,SAVE ][ ,NOTRANSLATE ]) | 

| | | [,DEST= {symbolic address | YES) ] — >TCAH only | 

III I 

i i i i 

The 3735 Programmable Buffered Terminal may be serviced by CICS/VS in 
response to terminal— initiated input, or as a result of an automatic or 
time— initiated transaction. Both are explained below. 



AUTOANSWER 

The 3735 transaction is attached by CICS/VS upon receipt of input from a 
3735. Data is passed to the application program in 476— byte blocks; 
each block (one buffer) may contain multiple logical records. The final 
block may be shorter than 476 bytes; zero— length final blocks are not, 
however, passed to the application program. If the block contains 
multiple logical records, the application program must perform any 
necessary deblocking functions and the gathering of partial logical 
records from consecutive reads. 

It is recommended that the user spool input data from a 3735 to an 
intermediate data set (for example, an intrapartition destination) to 
ensure that all data has been captured before deblocking and processing 
that data . 

The application program must follow 3735 conventions and read to end— 
of— file before attempting to write FDPs (form description programs) or 
data to the 3735. For this reason, the EOF=symbolic address operand 
must be used with each DFHTC TYPE=READ request. When the EOF branch is 
taken, the user may begin to write FDPs or data to the 3735, or, 
optionally, request CICS/VS to disconnect the line. 

It is possible that the 3735 will transmit the end— of— file condition 
immediately upon connection of the line. For this reason the user must 
code the initialization request (DFHTC EOF=symbolic address) before 
issuing any other terminal control requests. 

The user is responsible for formatting all special message headers 
for output to the 3735 (for example, SELECTRIC, POWERDOWN) . If FDPs are 
to be transmitted to a 3735 with ASCII transmission code, the 
NOTRANSLATE operand must be included in the DFHTC TYPE=WRITE request for 
each block of FDP records. 

The user must issue a DFHTC TYPE=DISCONHECT macro instruction when 
all output has been transmitted to the 3735. If the application program 
ends during batch write mode prior to issuing the DISCONNECT request, 
CICS/VS forces a 3735 "receive abort" condition and all data just 
transmitted is ignored by the 3735. 
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AUTOCALL AND TIME-INITIATED 

In automatic and time— initiated transactions, all considerations stated 
above except use of the DFHTC EOP=symbolic address macro instruction 
apply when CICS/VS dials a 3735. The DFHTC EOF=symbolic address macro 
instruction is not used. 

CICS/VS connects the line and allows the user to indicate the 
direction of data transfer by means of the first terminal control 
reguest. If this first request is a WRITE and the 373 5 has data to 
send, the 3735 causes the line to be disconnected. 
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3740 Data Entry System 



I 

DFHTC | TYPE=(READ[ , WAIT ][ , SAVE]) 

j [ ,ENDFILE=symbolic address] 

| [ ,ENDINPT=symbolic address] 
I 



->except TCAM 
->except TCAM 



I 

DFHTC | TYPE=(WRITE[,WAIT][ ,SAVE] 

| [ ,ENDFILE ][ ,ENDOUTPOT ][ TRANSPARENT ]) 

j [ ,DEST= {symbolic address | YES) ] — >TCAM only 



The 3740 Data Entry System may be serviced by CICS/VS as a batch or 
inquiry mode application. Considerations for both modes are described 
in the following paragraphs. 



BATCH MODE APPLICATIONS 



In batch mode, the 3740 sends multiple files of data to CICS/VS during a 
single transmission. All input data files must be sent to CICS/VS 
before the 3740 is able to receive data from CICS/VS. When able to 
receive, the 3740 accepts multiple files of data in a single 
transmission. To communicate in this manner, a means is provided in the 
DFHTC macro instruction for identifying end-of— file, end— of— input, and 
end— of-output conditions. 

When sending data to the 3740, the DFHTC TYPE=ENDFILE macro 
instruction must be issued after each file to signal the end-of— file 
(EXT) condition to the 3740. The DFHTC TYPE=ENDOUTPUT macro instruction 
should be issued after all data has been sent to the 3740 (EOT) and must 
be immediately preceded by a DFHTC TYPE=ENDFILE macro instruction. Once 
end— of— output is signalled in this manner, no additional WRITES should 
be issued. The WRITE, ENDFILE, and ENDOOTPUT parameters may be combined 
in the DFHTC macro instruction. For example, a DFHTC 

TYPE= (WRITE, ENDFILE) causes a write operation followed by an end-of— file 
signal. A DFHTC TYPE= (WRITE, ENDFILE, ENDOUTPOT) causes a write 
operation, an end— of— file signal, and then an end-of-output signal. A 
DFHTC TYPE= (ENDFILE, ENDOUTPOT) causes an end-of-file signal followed by 
an end-of-output signal. The placement of the parameter within the 
macro instruction has no effect on the sequence. 

N ote : If ENDFILE is combined with any other parameter and SAVE is also 
present, the TIOA used to write the end— of— file record will be current 
TIOA after return from terminal control. 
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3767 Interactive Logical Unit 



I I I 

| | | DFHTC | TYPE= (READ[ , WAIT ][ , SAVE]) 

II | [ ,EOC=symbolic address] 

I I I 

i i i 



TYPE= (WRITE[ ,WAIT ][ ,SAVE ][ ,L AST ]) 
[ ,FORCE=YES] 
[,CCOMPL=NO] 
[,DEFRESP=YES] 
[ ,DEST= {symbolic address | YES} ] — >TCAM only 




| DFHTC | TYPE=SIGNAL 

I j { / SIGADDR=symbolic address |,WAIT=YES) 

I I 

.1 i 



3770 Interactive Logical Unit 



I | | DFHTC | TYPE=(READ[ ,WAIT ][ ,SAVE ]) 

I | | [ ,EOC=symbolic address] 



1 t 1 

1 1 1 


1 

1 




III 


1 



DFHTC 



TYPE= (WRITE[ ,WAIT][ , SAVE ][ ,LAST ]) 
[ ,FORCE=YES] 
[,CCOMPL=NO] 
[ ,DEFRESP=YES] 
[ ,DEST= {symbolic address|YES) ] — >TCAM only 



III 1 


1 

1 
1 
1 

L . , , 


1 

| DFHTC 

1 1 

1 
, — t _.. _ _i 


TYPE=SIGNAL 

{,SIGADDR=symbolic address 


| ,WAIT=YES} 


i 

1 

1 

1 
i 
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3770 Batch and Batch Data Interchange Logical Unit 




TYPE= (READ[ ,WAIT ][ ,SAVE )) 

[ ,EODS=symbolic address] 
[ ,EOC=symbolic address] 
[ , INBFMH=symbolic address] 



TTPE=(WRITE[ , WAIT ][, SAVE ][ ,LAST ]) 
[,FMH={NO|YES} ] 
[ ,CCOMPL=NO] 
[ ,DEFRESP=YES] 
[ ,DEST= {symbolic address | YES} ] — >TCAM only 




3770 Full Function Logical Unit 




DPHTC | TYPE=(READ[ ,WAIT][ ,SAVE]) 

| [ ,EOC=symbolic address] 

| [ r INBFMH=symbolic address] 



DFHTC 



TYPE=(WRITE[ ,WAIT][ r SAVE][ ,LAST ]) 
[ ,FMH={NO|YES} ] 




SP=YES] 

{symbolic address! YES} 



->TCAM only 



3780 Data Communications Terminal 



Support and macro instruction syntax identical to System/3 



216 



CICS/VS APRH(HL) 



3790 Inquiry Logical Unit 



I I I 

I | | DFHTC | TYPE=(READ[, WAIT ][, SAVE]) 

|| I [ ,EOC=symbolic address] 

I I I 

i i 1 



I I 

| DFHTC | TYPE=(WRITE[ ,WAIT][ ,SAVE ][ ,LAST ]) 

| | [,FMH={NO|YES} ] 

| | [,CCOMPL=NO] 

| | [,DEFRESP=YES] 

| | [ ,DEST= {symbolic address| YES} ] — >TCAM only 

I I 

.1 i 



3790 Full Function Logical Unit 



I I 

| DFHTC | TYPE=(READ[,WAIT][ ,SAVE]) 

| | [ ,EOC=symbolic address] 

| | [ ,INBFMH=symbolic address] 



i 1 

I I 

| DFHTC | TYPE=(WRITE[ , WAIT ][ , SAVE ][ , LAST]) 

| | [,FMH={NO|YES} ] 

| | [,CCOMPL=NO] 

| | [ ,DEFRESP=YES] 

| | [ ,DEST= {symbolic address | YES} ]- 



->TCAH only 



3790 (SCS Printer) Logical Unit 



TYPE= (WRITE[ ,WAIT ][ ,SAVE ][ ,LAST ]) 
[ # CCOMPL=NO] 
[ ,DEFRESP=YES] 
[ ,DEST= {symbolic address|YES} ] — >TCAH only 




3790 (3270-Display) and 3790 (3270-Printer) Logical Units 

These logical units are sometimes referred to collectively as the 3270 
compatibility logical unit. Support and macro instruction syntax are 
the same as for the 3270 logical unit, apart from the following 
exceptions: 
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DPHTC TYPE=READB is not supported for the 3270— printer logical 
unit. 

DPHTC TYPE=COPY is not supported for the 3270-display logical unit. 

When using the DFHTC TIPE=PRINT macro, if FEATURE =PTR ADAPT has been 
specified in the TCT, allocation of the printer is controlled by 
the 3790. If FEATURE=PTR ADAPT has not been specified, allocation 
of printers is governed by the PRINTTO and ALTPRT options specified 
in the TCT. 



3790 Batch Data Interchange Logical Unit 

Support and macro instruction syntax identical to 3770 Batch Logical 
Unit. 
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7770 Audio Response Unit 



I I 

| DFHTC | TYPE=(READ[,WAIT][ ,SAVE]) 

I I 

.1 1 



I I 

| DPHTC | TYPE=(WRITE[ , WAIT ][ , SAVE ]) 

I I 

.1 I 



Although CICS/VS does not distinguish between special codes (characters) 
entered at an audio terminal (for example, the 2721 Portable Audio 
Terminal) , an application program is not precluded from performing 
special functions upon encountering these codes. For example, the 
following special hexadecimal codes may be entered from a 2721: 



Key 


|Code 




CULL END 


| 37 


(see 


note) | 


CNCL 


|18 






# 


|3B 


(see 


note) or 7B | 


VERIFY 


| 2D 






RPT 


I3D 






EXEC 


|26 


(see 


note ) | 


F1 


|B1 






F2 


|B2 






F3 


IB3 






F4 


|B4 






F5 


IB5 






00 


|A0 






000 


|3B 


(see 


note) or BO | 


IDENT 


111, 


12, 


13, or 14 plus two other characters | 



Note : These codes cause a hardware interrupt and are in the terminal 
input/output area (TIOA) immediately following the data; the codes are 
not included in the data length. 

For further information concerning the 2721, see the publication 2721 
Portable Audio Terminal Component Description . 

The following special hexadecimal codes may be entered from a Touch- 
Tone telephone (Touch— Tone is the trademark of the American Telephone 
and Telegraph Company.) 



|Key |Code 



I* 
l# 



|A0 

|3B or B0 



The * and # characters of a Touch— Tone telephone correspond to the 00 
and 000 characters, respectively, on a 2721 Portable Audio Terminal. 
The # and 000 characters cause an end— of— inquiry (EOI) hardware 
interrupt (X , 3B t ) unless the EOI Disable feature (#3540) is installed on 
the 7770 Audio Response Unit Model 3. If this feature is installed, the 
user can elect that neither, or only one, of the # and 000 characters 
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will cause a hardware interrupt. At the option of the user, either or 
both of the # and 000 characters do not cause a hardware interrupt, are 
presented in the TIOA with the rest of the data, and are included in the 
data length. 

If, after receiving at least one character from a terminal, no other 
characters have been received by the 7770 for a period of five seconds, 
the 7770 automatically generates an EOI hardware interrupt that ends the 
read operation. 



LUTYPE4 Logical Unit 




TYPE=(READ[,WAIT][ ,SAVE]) 

[ ,EODS=symbolic address] 
[ ,EOC=symbolic address] 
[ ,INBFMH=symbolic address] 




TYPE= (WRITE[ ,WAIT][ ,SAVE ][ ,LAST ]) 
[,FMH={N0|YES} ] 
[,CC0MPL=N0] 
[ ,DEFRESP=YES] 



| DFHTC | TYPE=SIGNAL 

I | {,SIGADDR=symbolic address | ,WAIT=YES) 



I 



The TYPE=SIGNAL macro instruction is required to detect a hard 
request change direction (RCD) signal from the terminal. The 
application program should not issue a TYPE=WRITE macro instruction 
following such a signal. 

LUTYPE4 terminals can operate in unattended mode . The application 
programmer can detect unattended mode by testing the TCTTE field TCTEMOP 
under the mask TCTEMOPO. 
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Other CICS/VS-Supported Terminals 



I I 

I DFHTC | TYPE= (READ[, WAIT ][ , SAVE]) 



I I 

| DFHTC | TYPE= (WRITE[ ,W AIT ][ , SAVE]) 

I | [ ,DEST= {symbolic address| YES) ] >TCAM only 

I I 

.1 1 



TCAM Supported Logical Units (CICS/OS/VS Only) 



I DFHTC | TYPE=({READ|READL}[,WAIT][ ,SAVE]) 
| J [ ,INBFMH=symbolic address] 



TYPE=( {WRITE |WRITEL}[ ,WAIT ][ ,SAVE ][ , ERASE][ ,LAST] 
[ ,ERASEAUP]) 
[,FMH={NO|YBS} ] 
[ ,CTLCHAR={hex number | YES) ] 
[ / LINEADR={number|YES) ] 
[ ,DEST= {symbolic address | YES) ] 
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Operands of DFHTC Macro 

CCOMPL=NO 



• Used with VTAM logical units only. 

indicates that the last request/response unit (RU) sent as a 
result of this write request will not complete the chain. If 
this operand is omitted, the last RU will terminate the chain. 

Before this operand may be used, the system programmer must 
have specified that the application program may control 
outbound chaining indicators by coding a DFHPCT TTPE=OPTGRP 
macro instruction with the CCONTR=YES operand. If CCOMPL=NO is 
used without this support, the task will be abnormally 
terminated. 

There are a number of restrictions on the use of the CCOMPL=NO 
operand; these restrictions are as follows: 

• If CCOMPL=NO is used without the authority (CCONTR) of the 
system programmer, the task will be abnormally terminated. 

• CCOMPL=NO cannot be used if the DEPRESP=YES operand is 
specified. 

• If CCOMPL=NO is specified, the application program must not 
issue a read request until a write request that does not 
specify CCOMPL=NO has been issued; failure to observe this 
restriction will lead to abnormal termination of the task. 

• CCOMPL=NO is not valid for a combined write and read 
request, including conversational write operations. 
TYPE=LAST is ignored if it is not FOC or OC. 



CONNECT= 



• Used with 3650 interpreter logical units only. 

This operand specifies the type of connection to be 
established. 

ACTIVATE 

specifies that the 3650 application program will not 
communicate with the host CPU. 

CONVERSE 

specifies that the 3650 application program will 
communicate with the host CPU. 
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CTLCHAR= 



o Used for 3270 logical units, 3650 host -conversational 

(3270) logical units, 3790 (3270-display) , and 3790(3270- 
printer) logical units only. 

This operand is used (1) in a DPHTC TYPE=WRITE macro 
instruction to provide the hexadecimal representation of the 
write control character (WCC) that controls the requested write 
operation, or (2) except for the 3650 host conversational 

(3270) LO, in a DFHTC TYPE=COPY macro instruction to provide 
the hexadecimal representation of the copy control character 

(CCC) that controls and defines the copy function to be 
performed . 

hexadecimal number 

is the hexadecimal representation of the WCC or CCC 
required for the operation specified in the TYPE= operand 
of this DFHTC macro instruction. 



YES 



indicates that the appropriate bit configuration has been 
placed in TIOACLCR. 



For DFHTC TYPE=WRITE, if the functions defined by the WCC only 
are to be performed (that is, no data stream is to be 
supplied), TIOATDL must contain zero. If the CTLCHAR operand 
is omitted, all modified data tags are reset to zero, and the 
keyboard is restored. For DFHTC TYPE=COPY, if the CTLCHAR 
operand is omitted, the contents of the entire buffer 
(including nulls) are copied and the start printer flag is not 
on. 

DEFRESP=YES 

• Used with VTAM logical units only. 

indicates that a definite response is required when the write 
operation has been completed. DEFRESP=YES cannot be specified 
if the CC0MPL=N0 operand is used. 

This operand specifies, for this write operation only, that a 
definite response is required, even if neither the MSGINTEG 
operand nor the PROTECT operand has been specified in the 
DFHPCT TYPE=OPTGRP macro instruction by the system programmer. 



DEST = 



indicates that the output message is to be sent to a TCAM 
destination other than the source TCAM terminal. 

This operand is meaningful only for TCAM— supported terminals. 

symbolic name 

is the symbolic address of the storage area containing the 
TCAM destination to which the message must be sent. 

YES 

indicates that the application program has placed the four- 
byte message destination in TCTTEDES before issuing the 
WRITE. This can be used to allow dynamic selection of the 
message destination. 
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ENDFILE=symbolic address 

• Used for 3740 Data Entry System only. 

indicates the label of the routine that is to receive control 
when end— of— file is encountered on batch input. It is set when 
a null block is received, indicating the end of a physical 
file. The task must continue reading. 

BNDINPT=symbolic address 

• Used for 3740 Data Entry System only. 

indicates the label of the routine that is to receive control 
when end— of— input is reached on batch processing. It is set by 
CICS/VS when an end of transmission signal is received and the 
ENDFILE indicator was set. After this condition the task must 
not issue any further reads to the device but must return to 
CICS so that the 3740 can be set to receive a new batch of 
input. 

ENDMSG=N0 

indicates that the block sent as a result of the write reguest 
does not complete the message. If this operand is omitted, the 
message will be regarded as complete when the write reguest has 
been fulfilled. 

Before this operand may be used, the system programmer must 
have specified that the application program mtay control 
outbound chaining by coding a DFHPCT TYPE=OPTGRP macro 
instruction with the MSGPREQ=CCONTEL operand. If ENDMSG=N0 is 
used without this support, the task will be abnormally 
terminated. 

There are a number of restrictions on the use of the ENDMSG=N0 
operand; these restrictions are as follows: 

© If ENDMSG=N0 is used without the authority 

(MSGPREQ=CCONTRL) of the system programmer, the task will 
be abnormally terminated. 

o If ENDMSG=N0 is specified, the application program must not 
issue a read reguest until a write reguest that does not 
specify ENDMSG=N0 has been issued; failure to observe this 
restriction will lead to abnormal termination of the task. 

• ENDMSG=NO is not valid for a combined write and read 
reguest, including conversational write operations. 
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EOC=symbolic address 

• Used for logical units only . 

Specifies the label of the routine that is to receive control 
if the request/response unit (RtJ) is received with the end— of— 
chain (EOC) indicator set. If this operand is specified, the 
WAIT parameter of the TYPE operand is assumed- If an inbound 
FMH is received, the INBFMH operand will override this operand. 
If an end— of— data-set FMH is also received, the EODS operand 
will override both this operand and the INBFMH operand. 
(Overridden operands can be specified in a DFHTC TYPE=WAIT 
macro .) 

EODS=symbolic address 

• Used for 36 50 interpreter logical units, batch logical 
units, and LUTYPE4 logical units only. 

• Cannot be used for 3650 Host Command Processor logical 
units. 

Indicates the label of a user— written routine that is to 
receive control if an end-of— data— set FMH is received. The 
TIOA contains the EODS indicators. If EODS is specified, the 
WAIT parameter of the TYPE operand is assumed. If EODS is 
specified, and end-of— data-set is received, the EOC and INBFMH 
operands are overridden; they can be specified in a DFHTC 
TYPE=WAIT macro within the end-of— data-set routine. 

Symbolic address is the address to which control is to be given 
if the CICS EODS indicator is set on. The indicator is set 
when a READ is issued and there is no data remaining for this 
data set. 

EOF=symbolic address 

indicates the label of the routine that is to receive control 
when end— of— file is encountered on batch input. This operand 
can be used in a special initialization macro instruction, 
DFHTC EOF=symbolic address, to test for the end-of— file 
condition upon initial connection to a 373 5. It must be 
included in the initialization section of the application 
program that handles 3735 input, preceding other DFHTC macro 
instructions. 

Note ; When the EOF condition occurs, TIOATDL is set to binary 
zeros to indicate that the TIOA for the input operation 
contains no valid data. 



FMH= 



• Used for 3600 (3601), 3650 host-conversational (3 270), 3650 
host-command processor, LUTYPE4, 3770 batch, 3790 full 
function, 3790 inquiry, and 3790 batch data interchange 
logical units only. 

This operand indicates whether the function management header 
(FMH) has been placed in the TIOA by the application program. 
If FMH is omitted, NO is assumed. 

For the 3600 (3601) and 3790 inquiry logical units, an FMH is 
required and is provided as described below. For the 3650 
host— conversational (3270) logical unit, the FMH is required if 
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outboard maps are to be used; the FMH in such cases can be 
provided by BMS, if BUS is being used, or otherwise, by the 
application program. For LUTYPE4 and batch logical units, the 
FMH is required for device— selection and is provided as 
described below. 

NO 

indicates that the application program has not placed the 
FMH in the TIOA. For the 3600 (3601) and 3790 inquiry 
logical units, CICS/VS is responsible for placing the FMH 
in the TIOA; if NO is specified, space must be reserved in 
the TIOA for the FMH. For the 3650 host— conversational 
(3270) logical unit, CICS/VS does not build an FMH, and the 
data is transmitted unmodified. For all other logical 
units, no FMH is sent; refer to the appropriate CICS/VS 
subsystem guides for details of when an FMH is necessary. 

IBS 

indicates that the application program has placed the FMH 
into the TIOA. Refer to the appropriate CICS/VS subsystem 
guides for size and format of the FMH for a specific 
terminal. The FMH=YES and LDC=YES options are mutually 
exclusive. 

F0RCE=YES 

• Used for interactive logical units only. 

This operand indicates that the write operation is to be 
preceded by an outbound SIGNAL data— flow-control command to 
force the terminal into receive mode. This operand is used 
only for interactive logical units operating in contention 
mode, and is ignored otherwise. 

INBFMH=symbolic address 

specifies the label of the routine that is to receive control 
if the request/response unit (RO) contains an FMH, and CICS/VS 
has passed this FMH to the application program. The presence 
of an inbound FMH means that, if this operand is specified, the 
EOC operand is overridden. If an end— of— data-set FMH is 
received, the EODS operand will override the INBFMH operand. 
(Overridden operands can be specified in a DFHTC TYPE=WAIT 
macro.) 

For this operand to be effective, the system programmer must 
have specified INBFMH=ALL or EODS in the PCT entry for the 
transaction. If INBFMH=NO is specified, inbound FMHs will not 
be passed to the application program, and the INBFMH operand 
will never be operative. 



LDC 



• Used for the 3601 logical unit (but not for the 3614, even 
if attached to the 3601) only. 

This operand specifies the mnemonic to be used by CICS/VS to 
determine the logical device code (LDC) that is to be 
transmitted to the logical unit in the function management 
header. 
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mnemonic 

is the two— character mnemonic used to determine the 
appropriate LDC numeric value. The mnemonic represents a 
LDC entry in the DFHTCT TYPE=LDC macro instruction. 



YES 



LINEADR= 



indicates that the application program has placed the 
mnemonic in TCATPLDM . The LDC=YES and FMH=YES options are 
mutually exclusive. 



• Used for 3270 in 2260 Compatibility Mode only. 

This operand specifies that writing is to begin on a specific 
line of a 2260/2265 screen simulated on a 3270 operating in 
2260 compatibility mode. 

number 

is the hexadecimal equivalent of the starting line number, 
For the 2260, X'FO 1 through X^FB^ correspond with line 
numbers 1 through 12 respectively. For the 2265, X^O 1 
through X»FE* correspond with line numbers 1 through 15 
respectively . 



YES 



indicates that the hexadecimal equivalent of the line 
number has been placed in TIOALAC. 



NONVAL=address 

• Used with 3650 application programs only. 

This operand indicates the label of the user— coded routine to 
receive control if the name specified in the PRGNAME operand is 
invalid. 

NORESP=address 

• Used with 3650 logical units only. 

This operand indicates the label of a user— coded routine to 
receive control if there is a no error response. 

PRGNAME=name 

o Used with 3650 logical units only. 

This operand indicates the name of the 3650 application 
program. The name (up to eight characters) is transmitted to 
the 3651 for verification by the 3650 control program. 
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RDATT=symbolic address 

indicates the label of the routine to which control is to be 
transferred if the read operation that responds to a DPHTC 
TYPE=READ macro instruction is terminated by pressing the 
attention (ATTN) key rather than the return key. 

Note ; This operand is meaningful only if 2741 Read Attention 
support has been generated in the CICS/VS system. See "Read 
Attention" and "Write Break" under "2741 Communication 
Terminal" earlier in this chapter. 

SIGADDR=symbolic address 

© VTAM only 

specifies the symbolic address of the routine to be given 
control if SIGNAL is received. 



TYPE= 



describes the terminal or logical unit operations required, as 
follows: 



TYPE=CBUPF 

• Osed with 2980 General Banking Terminal only. 

This is a stand— alone parameter used to place a message in the 
common buffer of the 2972 terminal control unit; the 2972 
associated with the current TCTTE receives the output message. 
Both write and wait are implied. 

Note : The output message is translated according to the model 
of 2980 described by the current TCTTE. If more than one model 
is attached to a 2972 Terminal Control Unit, the contents of 
the common buffer are intelligible only to the model for which 
the message was translated. Since shift characters are added 
to the message by CICS/VS during translation, the length of the 
message is dependent upon the contents of the message. Up to 
23 characters, including shift characters, can be transmitted. 

TYPE=C0PY 

I • Valid only for BSC— connected devices which have the copy 

I feature, that is, BTAM remote connection, or VTAM non— SNA 

| remote connection. 

This parameter is used to copy the format and data contained in 
the buffer of one terminal into the buffer of another terminal 
attached to the same remote 3270 control unit. The terminal 
from which data is to be copied can be identified in either of 
two ways: 

1. Set TIOATDL to a value of 1, and the first byte of the 
output data area (TIOADBA) to the physical address of the 
terminal to be copied; or 
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2. Set TIOATDL to a value of 4 and the first four bytes of the 
output data area (TIOADBA) to the terminal identification 
of the terminal to be copied. If the terminal 
identification is less than four bytes, it must be left- 
justified with blank padding on the right. 

The copy control character (CCC) , which controls and defines 
the copy function to be performed, must be supplied in the 
CTLCHAR operand of the DFHTC macro instruction. 

Note ; For VTAM— supported 3270 logical units, it is not 
possible to supply the physical address of the terminal to be 
copied; the terminal identification must be supplied. 

TYPE=DISCONNECT 

• Switched lines and logical units only. 

For switched lines, DISCONNECT is used to break the line 
connection between the terminal and the computer; if the 
terminal is a buffered device, the data in the buffer (s) is 
lost. 

• CICS/VS does not automatically disconnect a 3270 display at 
the end of a transaction. A disconnection occurs at the 
request of a terminal operator, at the request of the 
application program (through this macro instruction) , or 
after a specified number of time— outs are encountered by 
DFHTEP for the terminal. (Refer to the CICS/VS System 
Pro grammer' s Ref erence Manual for information about 
DFHTEP. ) 

• When used with a TCAM terminal or logical unit, DISCONNECT 
sets the X'OS' bit in the communication control byte (CCB) 
sent to TCAM. The message handler should provide the 
necessary function (that is, issue IEDHALT, to terminate 
the logical— unit session) for disconnect. 

• When used with VTAM logical units, DISCONNECT, which does 
not become effective until the task has been terminated, 
terminates the session, without causing a physical 
disconnection . 

TYPE=ENDFILE 

• Used for 3740 Data Entry System only. 

indicates that an end-of— file record is to be written to the 
terminal. 

TYPE=END0UTP0T 

• Used for 3740 Data Entry System only. 

indicates that an end— of -output record is to be written to the 
terminal. 

TYPE=EODS 

• Used with 3650 interpreter logical units only. 

causes an end of data set FMH to be sent on behalf of the task. 
An I/O area need not be supplied by the CICS/VS application 
program. Refer to the CICS/VS 3650 Guide for details about 
communicating with a 3650 application program. 
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Note ; If the application receives the FMH, the FMH may have 
been presented on completion of a previous read request. The 
actual end of the data set is not until the CICS EODS indicator 
is set on. 

TYPE=ERASE 

• Used with 2260 Display Station, 3270 Information Display 
System, 3270 logical units, 3650 host -conversational 
logical units, 3790 (3270-display ) , and 3790 (3270-printer) 
logical units only. 

This parameter is used with the WRITE or WRITEL operand. It 
blanks out the screen and sets the cursor to the upper left 
corner. Normally, TYPE=ERASE would be used on the first output 
reguest of a transaction to prepare the screen for new output 
data . 

TYPE=ERASE also sets the screen size to that specified for the 
transaction that issues the command. Therefore when switching 
from one screen size to another between transactions, a 
TYPE=ERASE must be issued to set the screen size of a new 
transaction. If one is not issued, the screen size will remain 
unchanged from a previous transaction^ setting. 

The CLEAR key, if used within a transaction, sets the screen 
size to its default. However, CICS/VS will reset the 
transaction specified size following a CLEAR operation. 

Note : To erase the screen, 

1. place the address of a TIOA into TCTTEDA, 

2. place a data length of into TIOADTL, and 

3. issue a DFHTC TYPE= (WRITE, ERASE) macro instruction. 

If operating in 2260 compatibility mode, the TIOA should 
contain only a start symbol and the data length in TIOATDL 
should be set to 1 before issuing the DFHTC TYPE= (WRITE, 
ERASE) . 

TYPE=ERASE and DEFRESP=YES are mutually exclusive. 

TYPE=ERASEAUP 

• Used with 3270 logical units, 3650 host— conversational 
(3270) logical units, 3790 (3270-display) and 3790 (3270- 
printer) logical units only. 

This parameter issues an "erase all unprotected" command 
command and causes the following functions to be performed: 

1. All unprotected fields are cleared to nulls (X^OO) . 

2. The modified data tags (MDTs) in each unprotected field are 
reset to zero. 

3. The cursor is positioned to the first unprotected field. 

4. The keyboard is restored. 

Neither WRITE, ERASE, nor COPY can be specified in a DFHTC 
macro instruction that includes the ERASEAOP parameter. No 
data stream is supplied. 
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• This parameter is not meaningful for a 3270 operating in 
2260 compatibility mode. 

TYPE=LAST 

signals CICS/VS that the WRITE is the last output for a 
transaction and, therefore, the end of a bracket. Specifying 
this parameter can improve system performance for VTAM logical 
units except when used with the 3270 logical unit. 

• This parameter nas no effect when used with a 3270 logical 
unit. 

TYPE=NOTRANSLATE 

prevents translation of form description program (FDP) records 
which are to be transmitted to a 3735 using ASCII transmission 
code. (For further information, see "3735 Programmable 
Buffered Terminal", earlier in this chapter.) 

TYPE=PASSBK 

• Used with 2980 General Banking Terminal only. 

This is a stand— alone parameter used to cause output to be 
printed on a banking passbook. Both WRITE and WAIT are 
implied. If a passbook is not present, no printing occurs. An 
error message can be sent to the operator of the terminal 
associated with the requesting task. 

TYPE=PRINT 

• Used with 3270 logical units, 3650 host— conversational 
(3270) logical units, 3790 (3270-display) , and 3790(3270- 
printer) logical units only. 

This parameter specifies that the data currently displayed on a 
3270 display is to be printed on an eligible 3270 printer. 

TYPE=PROGRAM 

• Used with 3650 devices only. 

This parameter is used to request the loading of a 3650 
application program. If the program is loaded, control is 
returned to the next sequential instruction following the DPHTC 
TYPE=program macro instruction unless NORESP=program is 
specified. Otherwise, control is returned to an address 
specified by one of the other operands of the macro instruction 
as listed below. 

TYPE=PSEUDOBIN 

indicates that the data being read is to be translated from 
System/7 pseudobinary representation to hexadecimal. (For more 
information about System/7 programming, see "System/7», earlier 
in this chapter.) 

TYPE=READ 

indicates that the data is to be read from a terminal or 
logical unit. 

When the contents of a 3270 buffer are read the programmer 
should be aware that the attention identifier byte and the 
cursor address are made available at TCTTEAID and TCTTECAD 
respectively. A set of standard symbolic names for testing the 
3270 attention identifier is provided in a copy book called 
DFHAID. For further details refer to "Standard Attention 
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Identifier List (DFHAID) " in the chapter "Basic Mapping 
Support". 



TYPE=READB 



• Used with BTAM 3270 and 3270 and 3790 (3270-display) logical 
units only. 

This parameter reads the contents of the 3 270 buffer, beginning 
at buffer location and continuing until all contents of the 
buffer have been read. All character and attribute sequences 
(including nulls) appear in the input data stream in the same 
order that they appear in the 3270 buffer. RBADB cannot be 
specified for TCAM— supported terminals nor can it be used for 
3790 (3270-printer) logical units. 

Note : Because of the relatively long transmision times 
reguired to transmit the entire contents of a remote 3270 
buffer, the READB parameter should be used primarily for 
testing and diagnosing; the COPY parameter, which permits a 
selective transfer of buffer contents should be used in all 
other cases. 

TYPE=READL 

• Used with 2260, or 3270 operating in 2260 compatibility 
mode, only. 

indicates that the keyboard is to remain locked at the 
completion of a data transfer. This parameter is applicable 
only to CICS/OS/VS, but may be used on a CICS/DOS/VS 
application if compatibility with CICS/OS/VS is desired. 

TYPE=RESET 

• Used with binary synchronous devices only. 

This operand is used to relinquish use of a communication line; 
the next BTAM operation will be a read or write initial. RESET 
is not supported by TCAM, because line control is performed by 
TCAM in the MCP. 

TYPE=SAVE 

in the case of a read operation, it indicates that the TIOA 
used in a previous terminal operation is not to be used as an 
input area; a new TIOA is acquired. For a write operation, it 
indicates that the TIOA whose address is in TCTTEDA is not to 
I be released upon completion of the write operation; however, 

I there is no guarantee that TCTTEDA will remain unchanged. 



TYPE=SIGNAL 



• Used with VTAM interactive and LUTYPE2, LUTYPE3, LUTYPE4 
and SCSPRT logical units, and VTAM 3600 (3601) logical 
units, only. 

Indicates that this macro instruction specifies the action to 
be taken by the application program when an inbound SIGNAL 
data— flow— control command is received from the logical unit. 

The four— byte field TCTESIDI in the terminal control table 
terminal entry (TCTTE) is set to the signal code received froi 
the logical unit. If a hard request change direction (RCD) 
signal is received (signal code X^OOOIOOOO 1 ) from an LUTYPE4 
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unit, the transaction should either end or read from the unit. 
An attempt to follow the signal with a write would be an error. 

Most logical units will send a signal with a code of 
X^OOOIOOOO 1 when an attention key is pressed. 

| TYPE=STRFIELD 

| • Assembler language only. 

| specifies that the TIOA contains structured fields. If this 

| operand is specified , the contents of all structured fields 

| must be handled by the application program. (Structured fields 

| are described in the CICS/VS IBM 3270 Guide .) CTLCHAR and 

| ERASE are mutually exclusive with STRFIELD and their use will 

| generate an MNOTE. 

TYPE=TEXT 

• Used with 3270 only. 

is meaningful only whan used in conjunction with a READ 
reguest. It specifies a temporary override of the uppercase 
translation feature of CICS/VS to allow the task to receive a 
message containing both uppercase and lowercase data. 

TYPE=TRANSPARENT 

• Applicable to System/3 when it indicates that output is to 
be sent in transparent mode (with no recognition of control 
characters, and accepting any of the 256 possible 
combinations of eight bits as valid transmittable data). 

• Applicable to System/7 when it indicates that the data 
being read is not to be translated. 

TYPE=WAIT 

ensures that the terminal or logical unit operation reguested 
in the macro instruction is completed before starting 
subsequent processing. WAIT can be coded separately from a 
| READ to accomplish overlapping of logical unit I/O operations; 

or with the EOC, EODS, or INBPMH operand, for example, to give 
control to user— written routines from within an end— of —data— set 
routine entered as a result of specifying the EODS operand. 

TYPE=WRITE 

indicates that data is to be written to a terminal or logical 
unit. 

TYPE=WRITEL 

• Used for a 3270 operating in 2260 compatibility mode only. 

This parameter indicates that the keyboard is to remain locked 
if locked previously, or to remain unlocked if unlocked 
previously, at the completion of data transfer. 
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If DFHTC macro instructions are issued in the following 
sequence, the keyboard is locked or unlocked as indicated: 



READ 


L 


WRITEL 


L 


READL 


L 


READL 


L 


WRITEL 


L 


WRITEL 


L 


WRITE 


U 


WRITEL 


U 


WRITEL 


U 


READ 


L 


WRITE 


U 


READL 


L 


READ 


L 


WRITEL 


L 



VALID=address 

• Used with 3650 devices only. 

This operand indicates the label of a user -coded routine to 
receive control if the name specified in the PRGNAME operand is 
valid but sufficient resources are not available in the 3651 to 
initiate the 3650 application program. This routine can 
determine whether a DFHIC TYPE=INITIATE or DFHIC TYPE=PUT macro 
instruction is to be issued in order to restart the 36 50 
application program later. 

WAIT=YES 

specifies that the task is to be suspended until SIGNAL is 
received. This request is ignored if the logical unit cannot 
send a SIGNAL command; the contents of field TCTESIDI will be 
set to X^OOOOOOO 1 in these circumstances. 

WRBRK=symbolic address 

is the symbolic address to which control is transferred if a 
write operation started in response to this DFHTC TYPE=WRITE 
macro instruction is interrupted by the terminal operator 
pressing the Attention (ATTN) key. 

• This operand is meaningful only if 2741 Write Break support 
has been generated into the system, an option available 
only under CICS/OS/VS. See "Read Attention" and "Write 
Break" under "2741 Communication Terminal" earlier in this 
chapter. 
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Chapter 4.3. Basic Mapping Support 



Basic mapping support (BMS) provides the CICS/VS application programmer 
with various formatting services that assist in interpreting input data 
streams from and preparing output data streams to the terminal network. 
These formatting services are provided by BMS modules that act as an 
interface between the user's application program and the CICS/VS 
terminal control program. 

The application program passes data to BMS and receives data from BMS 
in a device— independent format. BMS macro instructions are issued by 
the application program to control formatting of the data and to 
initiate input from and output to the terminal network. 



Advantages of BMS 

The two principal advantages to be obtained by using BMS are device 
independence and format independence. 



DEVICE INDEPENDENCE 

Device independence permits the application program to send data to a 
terminal or to receive data from a terminal without regard for the 
physical characteristics of the terminal. BMS can be used for 
communication with any of the following devices and logical units: 

1050 

2740 

2741 

2770 

2780 

2980 Models 1 and 2 

2980—4 (keyboard and printer only) 

3270 

3780 

TWX 

Tape storage devices 

Disk storage devices 

CRLP (a device declared as card— reader— in/line— printer— out) 

TCAM-connected terminals (defined by TRMTYPE=TCAM in DFHTCT 

TYPE=TERMINAL macro) 
TCAH logical units (defined by TCAMFET=SNA in DFHTCT TYPE=LINB macro 

and SESTYPE=3600|3767|3770 |3790 | BCHL0| INTLU in DFHTCT 

TYPE=TERMINAL macro) 
VTAM logical units: 

3270 

LUTYPE2 

LUTYPE3 

LUTYPE4 

SCSPRT 

3600 

3650 (host-conversational (3270) and interpreter LUs only) 

3767 

3770 

379 (all except inquiry LU) 
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Some special BMS programming considerations that apply only to 
particular terminal subsystems are described in the various CICS/VS 
subsystem guides (for example, the IBM 3600/3630 Guide ) . These guides 
are listed in the Bibliography . 

With BMS, a CICS/VS installation with more than one type of terminal 
need provide only one program for each application transaction to 
support all terminal types in the installation. BMS identifies which 
terminal type is requesting use of the application program and provides 
for the conversion of the device— dependent data stream to and from the 
device— independent format used by the application program. A CICS/VS 
installation using only one type of terminal may nevertheless wish to 
use the formatting services of BMS to facilitate the addition of other 
terminal types or the conversion to another terminal type in the future, 



FORMAT INDEPENDENCE 

Format independence permits the application program to provide data to 
one or more terminals or to receive data from a terminal without regard 
for the physical placement of fields within the data stream or on the 
terminal. 

All references to data by the application program are through 
symbolic field names. The placement of fields within the data stream is 
accomplished by BMS through the use of information stored in data format 
tables called maps . A CICS/VS installation in which BMS is used may 
rearrange the fields to be included in a terminal message by simply 
changing some values stored in the map that defines the format of the 
message. The application program that causes the message to be written 
need not be modified. Programming maintenance can thus be considerably 
simpler than if BMS were not used. 

Format independence also permits certain constant information, such 
as headings, field— identifying keywords, and 3270 screen formats, to be 
stored in maps. These constants can be modified simply by changing 
their values in the maps. Any programs that refer to the maps benefit 
from the changes, but none of the programs themselves need be modified. 

The format independence provided by BMS may be compared with the 
independence provided by DL/I for data bases. Both remove from the 
application program the requirement to know the physical placement of 
fields within the data record or message. Fields may be physically 
rearranged, removed, or added without necessitating program maintenance 
on all application programs using the record or message. 



Facilities of BMS 

The facilities that BMS provides are data mapping and formatting, 
terminal paging, and message routing. 
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DATA MAPPING AMD FORMATTING 

Data mapping is the technique used by BMS to convert the standard 
device— independent data format that the application program uses to and 
from the device— dependent data stream required for the particular 
terminal type in use. Device— dependent control characters are embedded 
or removed by BMS during this processing. 

The application program may select any of three standard data formats 
in which to provide or accept data from BMS: field data format, block 
data format, or text data format. 

When field data format is used, data is passed to BMS as separate 
fields. Each field is given a symbolic field name by the application 
programmer. This name is used when passing data to, or retrieving data 
from, BMS. Each field consists of a two— byte length area (used by BMS 
on input) , a single attribute byte (used for 3270 output operations 
only, but present for all terminal types), and the data area. A map 
describing the position of the field when displayed or printed, the data 
length, and other information about each field is created to control the 
mapping function. 

When block data format is used, data is passed to BMS as line 
segments. Fields positioned within the line segments may be given 
symbolic field names to aid the application program in positioning the 
fields. Each field provides for a single attribute byte and the data 
area. A gap consisting of several blanks may separate consecutive 
fields in the line segment. A map is used to describe the number and 
lengths of line segments, the field positions when displayed or printed, 
data lengths, and other necessary information. 

When text data format is used, output data consisting of a data 
stream with optional new— line (X'15 1 ) characters is passed to BMS. BMS 
divides the data stream into lines no longer than those defined for the 
particular terminal to which the data stream is related. BMS will only 
allow a line break to occur where it encounters a blank (X^O 1 )* If a 
word will not fit into the space remaining in a line, BMS places the 
whole word on a new line. If new— line characters are included in the 
data stream, they too are honored. CICS/VS inserts the appropriate 
leading characters, carrier returns, and idle characters, and eliminates 
trailing blanks from each line. If tab control characters are contained 
in the data stream, the user should also supply all the necessary new- 
line characters. Maps are not used with text data format. 

Field data format is the commonest data format for both display and 
printer terminals. Block data format may be used with both display and 
printer terminals, but it is more useful for input operations on printer 
terminals. Text data format is used with both display and printer 
terminals and is especially convenient for handling data that is not 
divided into fields. When text data format is used with a 3270 device, 
an attribute byte appears on the 3270 as a blank at the beginning of 
each line and in front of each new piece of data. 
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TERMINAL PAGING 

Terminal paging permits the application program to (1) combine several 
small mapped data areas into one or more pages of output, or (2) prepare 
more output than can be contained in one page of output. By definition, 
a page is the physical area of a terminal on which data is displayed or 
printed at one time. The size of the area (in numbers of lines and 
columns) is specified for the particular terminal in the CICS/VS 
terminal control table by the system programmer. 

Since a page of output may be constructed by BMS from several small 
maps, it is convenient to generate these maps together in a map set. A 
map set is a collection of maps generated and stored together in the 
CICS/VS program library. A reference to one map in the map set causes 
the entire map set to De loaded into storage for the duration of the 
task or until another map set is referred to by the task. DFHMSD, 
DFHMDI, and DFHMDF macro instructions, described later in this chapter, 
are used in constructing the map set. 

During execution, the application program issues DFHBMS TYPE=PAGEBLD 
macro instructions to position portions of an output page. If all the 
data cannot be contained on one page, BMS recognizes an overflow 
condition and can transfer control to an overflow routine within the 
application program. This routine normally causes the current page to 
be written to temporary storage, a new page to be started, a heading to 
be placed on the new page, and the data causing the overflow to be 
mapped on the new page. As each page of the output message is 
completed, the page is written to temporary storage to await completion 
of the loqic al_me s saqe. A logical message is the result of one or more 
BMS requests for output services all of which have the same disposition 
(OUT, STORE, or RETURN, as explained later in this chapter). To cause 
the logical message to be completed, the application program issues a 
DFHBMS TYPE=PAGEOUT macro instruction. Alternatively, the logical 
message is completed upon termination of the application program unless 
a short-on— storage condition exists, in which case the logical message 
is deleted. 

Terminal paging provides the additional function of building a 
logical message without the use of maps. A DFHBMS TYPE=TEXTBLD macro 
instruction is issued to request this type of page building. The data 
is passed to BMS as text data, which BMS places on succeeding lines (and 
pages, if necessary) without reference to maps. A word is not split 
between lines; any word that cannot fit on the remaining portion of a 
line is placed on the next line. The formatting of the logical message 
can be controlled through the data itself by embedding new— line 
characters (X*15») within the data. To cause the TEXTBLD logical 
message to be completed, the application program issues a DFHBMS 
TYPE=PAGEOUT macro instruction or terminates execution. 

DFHBMS TYPE=PAGEBLD and TYPE=TEXTBLD macro instructions cannot be 
used to build portions of the same logical message. The process of 
building a logical message can be discontinued by means of a DFHBMS 
TYPE=PURGE macro instruction. This instruction deletes the portions of 
the message already built in main storage or on temporary storage. 



MESSAGE ROUTING 

Message routing permits an application program to build and route a 
logical message to one or more terminals. The message is automatically 
scheduled for each designated terminal, to be delivered as soon as the 
terminal is available to receive messages or at some future time. 
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The page building facility of BMS is used for message routing, so the 
design of application programs is very similar for the two facilities. 
Message routing allows application— built messages to be sent to any 
prescribed terminals. 

To initiate a routing operation, the application program issues a 
DFHBMS TYPE=ROUTE macro instruction followed by DFHBMS 

TYPE= (PAGEBLD, STORE) or TYPE= (TEXTBLD, STORE) instructions to build the 
logical message that is to be routed. A DFHBMS TYPE=PAGEODT macro 
instruction terminates the page building and causes the message to be 
routed. When individual logical messages are routed to a terminal, they 
are not necessarily delivered in the sequence in which they were issued. 
If a specific sequence is required, the pages must be output as one 
message. 

A parameter of the DFHBMS TYPE=ROUTE macro instruction points to a 
list of terminals to receive the routed message. The list may contain 
the terminal identification and operator identification of each terminal 
designated to receive the message. If only a terminal identification is 
specified, the message is routed to that terminal, regardless of who is 
signed on at the terminal. If both the terminal identification and the 
operator identification are specified, the message is routed to the 
terminal but delivered only when the specified operator is signed on. 
If only the operator identification is specified, BMS scans the terminal 
control table and delivers the message to the first terminal at which 
the operator is signed on. 

Another parameter of the DFHBMS TYPE=ROUTE macro instruction is a 
specific operator class code. If specified, only an operator signed on 
with that class code may receive the routed message. One to twenty— four 
class codes may be assigned to operators in the CICS/VS sign— on table. 

The DFHBMS TYPE=ROUTE macro instruction further designates whether 
the message is to be delivered as soon as possible or at a specific time 
or after some interval of time. If the routed message cannot be 
delivered within a specified length of time, an error message may be 
returned to the terminal sending the message or to some designated 
alternative terminal. The message may be deleted, or it may be retained 
indefinitely — until delivered or until deliberately deleted by an 
operator at the receiving terminal. 

If a message is to be routed to more than one terminal type, BMS 
builds a device-dependent message for each terminal type. Each such 
message is stored on temporary storage until all terminals for which it 
is destined have received the message. If a terminal is scheduled to 
receive a message but is not eligible, the message is stored until one 
of the following conditions occurs: 

o A change in terminal status allows the message to be sent. 

o A time period (specified at system generation) has elapsed, causing 
the message to be deleted by BMS. 

• The message is deleted by the destination terminal. 

Another consideration of routing to different terminal types is the 
handling of overflow conditions. Since different terminal types may 
have different page sizes, the overflow condition is apt to occur at 
different times in page building. BMS returns control to an overflow 
routine in the application program, indicating which terminal type 
caused the overflow and how many pages have been created for that 
terminal type. 

If a message is routed to terminals with alternate screensize 
capabilities, the selection of the screensize to be used is taken from 
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the SCRNSZE parameter in the PCT for the routing transaction. (The 
SCRNSZE parameter is described in the CICS/VS System Programmer' s 
Reference Manual .) 

The message routing facility of BMS is an ideal tool for developing 
message switching and broadcasting applications. CICS/VS provides a 
generalized message switching transaction that uses the message routing 
facility of BMS. Use of the message switching transaction is described 
in the CICS/VS Operator's Guide . 



Mapping Concepts and Techniques 

Most of the facilities of BMS (text data format is the exception) 
reguire two forms of map to be defined by CICS/VS macro instructions and 
assembled offline in advance of running the application program. The 
two forms are: (1) a physical map used by BMS to convert data to or 
from the format desired by the application programmer, and (2) a 
symbolic description map used by the application programmer to 
symbolically refer to the data in the terminal buffer. The physical map 
is a table of information about each field, and is stored in the CICS/VS 
program library to be loaded by BMS at execution time. The symbolic 
description map is a set of source statements that are cataloged into 
the appropriate source library (Assembler, COBOL, PL/I, or RPG II) and 
copied into the application program when it is assembled or compiled. 

The programmer defines and provides names for fields and groups of 
fields that may be written to and received from the devices supported by 
BMS. The symbolic description map can be copied into each application 
program that uses the associated physical map. Data can thus be passed 
to and from the application program under the field names in the 
symbolic description map. Since the application program is written to 
manipulate the data under the field names, altering the map format by 
adding new fields or rearranging old fields does not necessarily alter 
the program logic. 

If the map format is altered, it is necessary in most cases to make 
the appropriate changes to the macro instructions that describe the map 
and then reassemble both the physical map and the symbolic description 
map. The new symbolic description map must then be copied into the 
application program and the program reassembled. There are certain map 
alterations that can be made without necessitating reassembly of the 
symbolic description map. 

An application program has access to the input and output data fields 
using the names supplied to the fields when the maps were generated. 
The application logic should be dependent upon the named fields and 
their contents but should be independent of the relative positions of 
the data fields within the terminal format. If it becomes necessary to 
reorganize or add to a map format, the existing application program must 
be reassembled to gain access to the new positions of these data fields. 
Reprogramming is not necessary to account for new fields or for the 
changed terminal format of those fields. 

By using BMS to construct and interpret data streams, application 
programmers can insulate application programs from the device— dependent 
considerations reguired to handle the data streams. If necessary, the 
application program has the facility to temporarily modify the 
attributes or the initial data of any named field in an output map. A 
collection of named attribute combinations is supplied within BMS so 
that the application program remains essentially independent of the data 
stream format . 
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The ability to progressively add to map definitions without 
obsoleting existing application programs permits the design and 
implementation of systems in a modular fashion with a progressive 
expansion of the screen formats. Design and programming of the first 
stages of applications can begin before later stages have been designed. 
These early implementations are protected from updates in the terminal 
formats. 

Note : To use pre— VS application programs requiring the BMS functions, 
the application programs must be reassembled. However, physical maps 
and symbolic description maps need not be reassembled provided that the 
COMPAT=PRE— VS operand is specified in the DFHSG PROGRAM=BMS system 
generation macro (described in the CICS/VS System Programmer's Reference 
M anua l) . 



MAP DEFINITION 

| All maps must be generated as members of a map set; a single map must be 

| generated as the only member of such a map set. A map set is a 

I collection of related maps that are generated and stored together in the 

| CICS/VS libraries. 

Map definition is accomplished through the use of three different 
macro instructions: DFHMSD, DFHMDI, and DFHMDF. 

The DFHMSD macro instruction 

© defines a map set 

• indicates whether a particular set of macros is for a physical map 
or for a symbolic description map 

• specifies whether the map is for input, output, or both 

• can specify the data format: field or block. 
The DFHMDI macro instruction 

• defines a map 

• defines the position of the map on the page, either absolutely or 
in relation to other maps 

• specifies the size of the map 

• can specify the data format: field or block. 
The DFHMDF macro instruction 

• defines a field within a map 

• specifies the position of the field 

• specifies the length of the field. 

The formats of these macro instructions are given later in this 
chapter. An example of their use and of the symbolic storage 
definitions generated is given in Appendix B. 

The map definition macro instructions are assembled twice, once to 
produce the map used by BMS, and once to produce the symbolic storage 
definition (or DSECT) that will be copied into the application program. 

Chapter 4.3. Basic Mapping Support 241 



N ote : In pre— VS versions of CICS, BMS provided support for the 3270 
Information Display System through DFHMDI and DFHMDF macro instructions 
only. For compatibility, DFHMDI and DFHMDF macro instructions written 
to use this support will be assembled correctly under CICS/VS BMS; 

| however, maps requiring functions that were not available in pre— VS 

I versions of CICS cannot be defined in this way. 



INPUT MAPPING 

For an input map, the maximum data length and the starting position of 
each field must be defined. 

The TIOA symbolic storage definition contains an area for the length 
of each input data field, followed by a flag byte and an area for the 
data itself. Space is reserved for the maximum number of bytes defined 
for each field. 

The program can access the length, flag, and data areas of any field 
by symbolic labels. The length area is a half word binary field and is 
addressed by the name "f ieldname .L" or "groupname.L". The flag is a 
one— byte field and is addressed by the name "fieldname .F" or 
"group nam e.F". The data portion of each field (or group of fields) is 
contiguous with the length and flag areas. A group of fields, or a 
single field not within any group of fields, has one data portion 
addressed by the name "groupname .1" or "fieldname. I". For fields 
contained within a group, there are no intervening length or flag areas 
(only "groupname.L" exists) but each field is addressed by a name 
"fieldname. I". 

In assembler language programs, the first byte of the first 
occurrence of a field defined by the DFHMDF operand 0CC0RS=n (where n is 
greater than 1) is named "fieldname D", and the first byte of the next 
occurrence of the field is named "fieldname N". These names refer to 
the first £>yte of the length area if DATA=FIELD is specified, and to the 
first byte of the attribute data if DATA=BLOCK is specified. 

In COBOL and PL/I programs, "fieldname D" is the name of the array of 
minor structures containing the length, flag, and data areas of the 
field. (For a description of the effects of the OCCURS operand in RPG 
programs, refer to the CICS/VS Application Programmer's Reference Manual 
for RPGII .) 

Note that " ." is a concatenation symbol used here only to show how 
the symbolic names are suffixed; the period is never actually coded. 
For example, in the case of field name XYZ, the data is referenced as 
XYZI; the data length is referenced as XYZL; and the flag is referenced 
as XYZF. 

The length specified for a field may differ from the number of 
characters that are entered for the field at program execution time. If 
more data is keyed than specified in the map, the data is truncated on 
the right to the number of characters specified. The length that is 
returned to the application program is the truncated length. If less 
data is keyed than specified, the remaining character positions are 
filled with blanks or zeros and the length of the keyed data is returned 
in the length field. 

The flag byte is normally set to X»00". However, if the field has 
been modified but no data has been sent (as, for example, if it has been 
modified to all nulls), the flag byte is set to X^O 1 and the length 
area is set to zeros. 
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Any fields that are entered as input but are not defined in the map 
are discarded. The length and data areas of any fields defined but not 
keyed are set to nulls (X'OO 1 ) . 

For a pen— detectable field, although no data is passed, a single data 
byte is reserved. This byte contains X^F 1 if the field is selected or 
X^O 1 if the field is not selected. The length area of a pen— detectable 
field contains a binary one if selected or a binary zero if not 
selected. 



OUTPUT MAPPING 

For each output field, the starting location, length, field 
characteristics, and default data (if desired) must be defined. 

The fields of an output map are assigned names in the DFHMDF macro 
instruction. The characteristic or attribute byte is named 
"fieldname. A" or "groupname. A" . For a field contained within a group, 
the data area is given the name "fieldname .0", but there is no separate 
attribute byte for the field. (Only the group name has the attribute 
byte.) For a group name, or a field not contained within a group, the 
data area is given the name "groupname. 0" or "f ieldname .0." 

In assembler language programs, the first byte of the first 
occurrence of a field defined by 0CCURS=n (where n is greater than 1) is 
named "fieldname D", and the first byte of the next occurrence of the 
field is named "fieldname N". These names refer to the first byte of 
the length area if DATA=FIELD is specified, and to the first byte of the 
attribute data if DATA=BLOCK is specified. 

In COBOL and PL/I programs, "fieldname D" is the name of the array of 
minor structures containing the attribute byte and data area of the 
field, together with the unused two— byte length field (described below) . 
(For a description of the effects of the OCCURS operand in RPG programs, 
refer to the CICS/VS Application Programmer's Reference Manual for 
R PGII . ) A field not contained within a group is treated as a group 
containing one field entry. An unused two— byte length field precedes 
each attribute byte and data field to provide a format similar to an 
input symbolic storage description TIOA. Application programs written 
to use pre— VS data formats are source compatible if all references to 
TIOA data are symbolic. 

Note that "." is a concatenation symbol used here only to show how 
the symbolic names are suffixed; the period is never actually coded. 
For example, in the case of field name XYZ, the data is referred to as 
XYZO; the attribute byte is referred to as XYZA. 

If output maps are to be used by application programs coded at 
command level, the TIOAPFX=YBS operand must be specified in the DFHMSD 
or DFHMDI macros that create the maps. Also, if the symbolic 
description maps are referred to by a PL/I program, the ST0RAGE=AUT0 
operand must be specified in the DFHMSD macro. 

When defining fields, the user may provide a name for any field that 
he wishes to refer to at execution time. Such names are associated with 
the fields in the symbolic storage definition of the TIOA to allow 
symbolic references to be made to them. The user may specify not only 
the characteristics of the field but also the default data to be written 
as output for a field when no data is supplied for that field by an 
application program. This facility permits the specification of titles, 
headers, and so forth, for output maps. The user may temporarily 
override the field characteristics, the data, or both field 
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characteristics and data of any field for which he has specified a name. 
The desired changes are simply inserted into the TIOA under the 
specified field name in the symbolic storage definition (symbolic 
description map) in the program. 

Note : Output field data supplied by the application program must not 
begin with a null character (X»00»)r or the entire field will be ignored 
by BMS. A suitable character to use in the first position is blank 
(X»40»). 

Pen-detectable fields should be "auto skip" to prevent data from 
being keyed into them. Because of the nature of pen— detectable fields, 
in most instances, they should not be modified. If the data field is 
modified, the application program must ensure that the first character 
is a »?», ••>», "6», or blank character; otherwise, the field is no 
longer pen— detectable. 

Fields that can be keyed should be delimited by a stopper field to 
ensure that all the data keyed and transmitted can be mapped. 



INPUT/OUTPUT MAPPING 

Input/output (INOOT) maps combining all the functions of input and 
output maps can also be created using the DFHMSD, DFHMDI, and DFHMDF 
macro instructions. 

The number of fields which can be specified for a COBOL or PL/I 
input/output map is limited. These limits are stated in the description 
of the DFHMDF macro instruction later in this chapter. 



MAP RETRIEVAL 

Map sets placed in the CICS/VS program library are accessed by BMS 
through program control DFHPC TYPE=LOAD macro instructions. Therefore, 
each map set name must be entered in the processing program table (PPT) 
by the system programmer. When device— dependent map sets are placed in 
the CIC5/VS program library, they must be identified by the device- 
dependent suffixed name, and a corresponding entry of the same name must 
appear in the PPT. (Device— dependent suffixes are described below under 
the * mapset 1 name of the DFHMSD macro instruction and under the SUFFIX 
and TERM operands of that macro.) 

To avoid having to load a map set during execution, an assembler- 
language programmer using the macro level interface may include the map 
set in the program, place the address of the map set at TCAMSMSA, and 
code MSETADR=YES in the DFHBMS macro. Alternatively, the programmer may 
code MSETADR=symbolic-address, where the symbolic address is the label 
of the map set. The MAP=map— name specification must also be provided 
with the MSETADR parameter to locate a specific map within the map set. 
Similarly, the MAPADR operand enables an assembler— language programmer 
to specify, directly or indirectly, the address of an individual map. 
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COPYING SYMBOLIC DESCRIPTION MAPS 

The BUS symbolic description maps must be copied into the application 
program as shown in the following examples. These examples use the 
macro level interface, examples using the command level interface are 

given in CICS/VS A pplica t i on Programmer's Refere nce Ma nual ( Command 

Level) . In the following examples, mapsetnamel, mapsetname2, and 
mapsetname3 are the names of members that contain the assembly of a BMS 
symbolic storage definition. 

1. Assembler— language COPY instructions for each symbolic storage 
definition. To ensure that each definition overlays the same area, 
the second and subsequent COPY instructions must be preceded by an 
ORG instruction to reposition the Assembler to the start of the 
TIOA data area. 

COPY DFHTIOA 
COPY mapsetnamel 
ORG TIOADBA 
COPY mapsetname2 
ORG TIOADBA 
COPY mapsetname3 

2. COBOL COPY statements for each symbolic storage definition. Note 
that mapnamell, mapname2I, and mapname3I in this example are the 
names of the first maps in the map sets. 

LINKAGE SECTION. 

01 DFHBLLDS COPY DPHBLLDS . 

02 TIOABAR PIC S9 (8) COMP. 



01 DFHCSADS COPY DFHCSADS. 

01 DFHTCADS COPY DFHTCADS. 

01 DFHTIOA COPY DFHTIOA. 

01 mapnamell COPY mapsetnamel, 

01 mapname2I COPY mapsetname2, 

01 mapname3I COPY mapsetname3, 



| Note : For M0DE=IN and MODE=INOUT the format of the COPY statement 
I is: 

I 

| 01 mapnamell COPY mapsetnamel 

I 

| For MODE=OUT the format of the COPY statement is: 

I 

| 01 mapnamelO COPY mapsetnamel 

3. PL/I %INCLUDE statements. 

^INCLUDE DFHTIOA; 

2 DUMMY CHAR (1) ; 
%INCLUDE mapsetnamel; 
95INCLUDE mapsetname2; 
^INCLUDE mapsetname3; 
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In addition to providing the BUS symbolic storage definition for the 
TIOA, the application programmer must establish addressability for this 
storage definition- Depending on the programming language used, this is 
accomplished as follows: 

1. Assembler— language L instruction to set up TIOABAR, normally from 
TCASCSA. For example: 

COPY DFHTIOA 
COPY mapsetnamel 

ORG TIOADBA 
COPY mapsetname2 
ORG TIOADBA 
COPY mapsetname3 



DFHSC TYPE=GETMAIN, * 

NUMBYTE=mapname.E-TIOADBA, * 

CLASS=TERMINAL, * 

INITIMG=00 

L TIOABAR, TCASCSA ESTABLISH TIOA ADDRESSABILITY 

Note : BMS offline macros generate a label at the end of each map 
description and a label at the end of each mapset description; 
these labels have the form , mapname.E» and •mapsetname.T 1 , 
respectively, where ••• is a concatenation symbol used only for 
documentational purposes. The start of each map, or mapset, can be 
referred to by the label TIOADBA. Thus an Assembler— language 
programmer can specify the amount of storage reguired in the way 
shown in the example above. 

2. COBOL 02 level statements immediately following the COPY statement 
for the Linkage Section Base Locator (BLL) . These 02 statements 
must be coded in the same order as the corresponding 01 statements. 
For example: 

LINKAGE SECTION. 

01 DFHBLLDS COPY DFHBLLDS. 

02 TIOABAR PIC S9(8) COMP . 
02 HAPBASE1 PIC S9 (8) COMP. 
02 MAPBASE2 PIC S9 (8) COMP. 
02 MAPBASE3 PIC S9 (8) COMP. 

01 DFHTIOA COPY DFHTIOA. 

01 mapnamel COPY mapsetnamel. 

01 mapname2 COPY mapsetname2. 

01 mapname3 COPY mapsetname3. 

PROCEDURE DIVISION. 

DFHSC TYPE=GETMAIN,NOMBYTE=120,CLASS=TERMINAL,INITIMG=00 
MOVE TCASCSA TO TIOABAR. 
ADD 12 TIOABAR GIVING MAPBASE1. 
MOVE MAPBASE1 TO MAPBASE2 MAPBASE3. 
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3. Set up the PL/I based pointer variable (BHSHAPBR) on which the map 
structures are based. For example: 



^INCLUDE DFHTIOA;; 
^INCLUDE mapsetnamel; 
56INCLUDE mapsetname2; 
56INCLUDE mapsetname3; 



/*EACH OF THESE MAPS IS*/ 
/♦BASED ON THE SAME POINTER*/ 
/♦VARIABLE - BMSMAPBR*/ 



DFHSC TYPE=GETMAIN, 
NUMBYTE=120, 
CLASS=TERMINAL, 
INITIMG=00 

TIOABAR=TCASCSA; 

BMSMAPBR=ADDR (TIOADBA) ; 



Note that this code assumes that the TIOAPFX operand of the DFHMSD 
and DFHMDI macro instructions has been omitted or coded as TIOAPFX=NO. 



Map Definition Macro Instructions 



The syntax and operand descriptions of the three map definition macro 
instructions (DFHMSD, DFHMDI, and DFHHDF) are given below. 
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DEFINING A MAP SET (DFHMSD MACRO INSTRUCTION) 



I BMS generates and stores map sets in the CICS/VS program library under 
the names selected by the application programmers. A reference to one 
map in the map set causes the entire map set to be loaded into storage 
for the duration of the task, or until another map set is referred to by 
the task. 

Information pertaining to an entire map set is specified in the 
DFHMSD macro instruction, which always appears at the beginning and end 
of each map set generation. The one at the beginning indicates whether 
physical maps or symbolic description maps are being generated; the one 
at the end indicates the end of the map set. 

All operands other than the TYPE operand of a DFHMSD macro 
instruction are the same for a physical map generation run and for the 
corresponding symbolic description map generation run. The application 
programmer should specify TYPE=MAP for the former, and TYPE=DSECT for 
the latter. Alternatively, physical maps and symbolic description maps 
can be assembled in the same job by the use of job control language 
options, as described in the CICS/VS System Programmer's Guide . 

The format of the DFHMSD macro instruction is as follows: 



mapset | DFHMSD 



TYPE={DSECT| MAP | FINAL} 

[ ,BASE=name ] 

[ , COLOR= {DEFAULT |BLUE | RED | PINK | GRE EN | TURQUOISE | 

YELLOW | NEUTRAL} ] 
[ ,CTRL= ([ PRINT ][ , {L40|L64|L80|HONEOM} ] 

[ ,FREEKB][, ALARM ][,FR SET]) ] 
[ ,DATA= {FIELD | BLOCK} ] 
[ ,EXTATT={NO|YES|MAPONLY} ] 
[ ,HILIGHT= (OFF I BLINK |REVERSE | UNDERLINE} ] 
[ ,HTAB=tab[ ,tab ] . . . ] 

[ ,LANG= {ASM | COBOL |PLI|RPG} ] RPG:DOS only 

[ ,LDC=mnemonic] 
[ ,MODE={IN|OUT|INOUT} ] 
[ ,OBFMT={YES|NO} ] 
[ ,PS={BASE|psid} ] 
[ ,STORAGE=AUTO] 
[,SUFFIX=n] 
[ ,TERM=terminal— type] 
[ ,TIOAPFX={YES|NO} ] 

[ ,VALIDN= ([MUSTFILL][,MUSTENTER]) ] 
[ , VTAB=tab[ ,tab ] . . . ] 



where: 
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map set 



TYPE = 



is the one— to seven— character name of the map set, to be 
specified in the MAPSET operand of any DFHBMS macro instruction 
that refers to the map set . The name must begin with an 
alphabetic character and, if the map is to reside in the 
CICS/VS program library, must differ from other map names or 
program names. 

A suffix specified by the SUFFIX operand, or based on the 
terminal type specified in the TERM operand of the DFHMSD macro 
instruction is appended to the map set name during assembly. 
This suffixed name is the name that should be used in the NAME 
card (OS) or the PHASE card (DOS) in cataloging the mapset (see 
the appropriate CICS/V S Sys tem Programm er' s Guide for further 
details) , and the name that should be specified by the system 
programmer in the PPT entry (see the CICS/VS System 
Programmer's Reference Manual ). The suffixes are tabulated in 
the description of the TERM operand, below. 

When a mapping operation is reguested by means of a DFHBMS 
macro instruction in an application program, CICS/VS 
automatically appends a similar suffix to the map set name 
specified in that instruction, and attempts to load a map set 
with the suffixed name. If the load is unsuccessful, that is, 
the suffixed map set name cannot be found in the library, 
CICS/VS will load a map set with an unsuffixed name (eguivalent 
to being suffixed with a blank) . CICS/VS obtains the suffix 
from the TCT terminal entry for the appropriate terminal 
(either the terminal associated with the transaction or, for 
routing, the destination terminal) , and this suffix depends on 
the terminal type specified in the TRMTYPE operand (together 
with the SESTYPE operand for VTAM terminals) of the DFHTCT 
TYPE=TERMINAL (or TYPE=LINE) macro. 

If the alternate page size is being used, as specified by the 
ALTPGE operand of the DFHTCT TYPE=TERMINAL system macro, and 
the ALTSFX operand of that same system macro has also been 
specified, an attempt will be made to load the map set that has 
the alternate suffix specified in the SUFFIX operand of the 
DFHMSD macro. If this load is unsuccessful, normal map set 
selection will occur. 

For example, if two maps are assembled, one with TERM=CRLP and 
the other with TERM=ALL, the first will be suffixed with A and 
the second with blank (that is, unsuffixed) . The system 
programmer should use these suffixed names in the PHASE/NAME 
cards and in the PPT entry. If a CICS/VS transaction now 
routes a message to two terminals, one of which has 
TRMTYPE=CRLP and the other TRMTYPE=L3277, TRMM0DL=2, BMS will 
attempt to load mapset. A and mapset. M to do the mapping in the 
two cases. The second of these will be unsuccessful, so BMS 
will then look for the unsuffixed map set name for routing to 
the 3277. 



indicates the generation function of the macro instruction. 
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DSECT 

indicates that this is a symbolic description map 
generation run to create the list of field names to be 
copied into an application program. If a single map set is 
to be used by application programs written in different 
languages, a separate DPHMSD TYPE=DSECT macro instruction 
must be written for each language to put the table of field 
names into the copy library of the language. 

NAP 

indicates that this is a physical map generation run to 
create the control information block used by BMS to perform 
mapping. This physical map is stored in the CICS/VS 
program library and loaded as required by BMS. The 
assembler— language application programmer can, 
alternatively, generate the map in his program and pass the 
address of the map to BMS instead of using this facility to 
generate and store the map beforehand in the CICS/VS 
program library. 

FINAL 

must be coded in the DFHMSD macro instruction that marks 
the end of the map set. If other parameters are coded in 
the DFHMSD TYPE=FINAL macro instruction, they will be 
ignored . 

BASE=nams 

is used to indicate that the same storage base will be used for 
the symbolic description maps from more than one map set. The 
same name is coded in the BASE operand for each map set that is 
to share the same storage base. Since all map sets with the 
same base describe the same storage, data related to a 
previously—used map set may be overwritten when a new map set 
is used. Furthermore, different maps within the same map set 
will also overlay one another. 

This operand is not valid for assembler— language or EPG II 
programs. 

As an example, assume that the following DFHMSD macro 
instructions are used to generate symbolic description maps 
(symbolic storage definitions) for two map sets. 

MAPI DFHMSD TYPE=DSECT, * 

TERM=278 0, * 

LANG=COBOL, * 

BASE=DATAREA1, * 
MODE=IN 

MAP2 DFHMSD TYPE=DSECT, * 

TERM=3270, * 

LANG=COBOL , * 

BASE=DATAREA1, * 
MODE=OUT 

The symbolic storage definitions of this example might be 
referred to in a COBOL application program as follows: 
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LINKAGE SECTION. 

01 DFHBLLDS COPY DFHBLLDS. 



02 TIOABAR PIC S9 (8) COMP. 
02 MAPBASE1 PIC S9 (8) COMP, 



01 DFHTIOA COPY DFHTIOA. 
01 DATAREA1 PIC X (1920) . 
01 name COPY MAPI. 
01 name COPY MAP2. 

MAPI and MAP2 multiply redefine DATAREA1; only one 02 statement 
is needed to establish addressability. However, the program 
can only use the fields in one of the symbolic map areas at a 
time. 

If BASE=DATAREA1 is deleted from this example, an additional 02 
statement is needed to establish addressability for MAP2; the 
01 DATAREA1 statement is not needed. The program could then 
refer to fields concurrently in both symbolic map areas. 

In PL/I application programs, the name specified in the BASE 
operand is used as the name of the pointer variable on which 
the symbolic storage definition is based. If this operand is 
omitted, the default name (BMSMAPBR) is used for the pointer 
variable. The PL/I programmer is responsible for establishing 
addressability for the based structures. 



C0L0R= 



specifies the default color for all fields in all maps in a 
set unless overridden explicitly by the COLOR option of a 
DFHMDI or DFHMDF macro. If this option is specified when 
EXTATT=NO, a warning will be issued and the option ignored, 
this option is specified, but EXTATT is not, EXTATT=MAPONLY 
will be assumed. 



map 



If 



CTRL= 



is used to specify device characteristics related to terminals 
of the 3270 Information Display System. CTRL=ALARM is valid 
for TCAM 3270 SDLC and VTAM— supported terminals (except 
interactive and batch logical units) ; all other parameters for 
CTRL are ignored. To be effective, this operand must be 
specified on the last (or only) map of a page unless the CTRL 
operand of the DFHBMS macro is being used to override the 
corresponding operand in the DFHMSD macro. If the CTRL operand 
is specified in the DFHMDI macro, it cannot be specified in the 
DFHMSD macro. 

PRINT 

must be specified if the printer is to be started; if 
omitted, the data is sent to the printer buffer but is not 
printed. This operand is ignored if the map set is used 
with 3270 displays without the Printer Adapter feature. 
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DATA = 



L40, L64, L80, HONEOM 

are mutually exclusive options that control the line length 
on the printer. L40, L64, and L80 force a carrier 
return/line feed after 40, 64, or 8 characters, 
respectively. HONEOM causes the printer to honor all new- 
line (NL) characters and the first end— of— message (EM) 
character that appear in displayable fields of the data 
stream. If the latter option is specified, the application 
program must insert the NL and EM characters into the data 
stream. If the NL character is omitted, a carrier 
return/line feed occurs at the physical end of the 
carriage. If the EM character is omitted, printing stops 
at the end of the 3270 buffer. 

FREEKB 

specifies that the keyboard should be unlocked after this 
map is written out. If omitted, the keyboard remains 
locked; further data entry from the keyboard is inhibited 
until this status is changed. 

ALARM 

activates the 3270 audible alarm feature. For a VTAM 
terminal ALARM signals BMS to set the alarm flag in the 
function management header; this feature is not supported 
by interactive and batch logical units. 

FRSET 

indicates that the modified data tags (MDTs) of all fields 
currently in the 3270 buffer are to be reset to a not- 
modified condition (that is, field reset) before any map 
data is written to the buffer. This allows the DFHMDF 
ATTRB specification for the reguested map to control the 
final status of any fields written or rewritten in response 
to a DFHBMS macro instruction. 



specifies the format of the data as seen by the application 
program . 

FIELD 

indicates that the data is passed as contiguous fields in 
the following format: 



|LL|A|data f ield| LL| A | data field |LL|A|etc. 

i . . 



LL is two bytes specifying the length of the data as input 
from the terminal (this field is ignored in output 
processing) . A is a byte into which the programmer may 
place an attribute to override that specified in the map 
used to process this data (see "Standard Attribute List and 
Printer Control Characters (DFHBMSCA) , " later in this 
chapter) . 
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BLOCK 

indicates that the data is passed as a continuous stream 
which is processed as line segments of the length specified 
in the map used to process this data set. The data is in 
the form that it appears on the terminal; that is, it 
contains data fields and interspersed blanks corresponding 
to any spaces that are to appear between the fields on 
output. The first byte of each line is the attribute byte; 
it is not available for data. EXTATT=YES cannot be used if 
DATA=BLOCK is specified . 

| A | data field | space | A | data field | space | A |data field | etc, 

i 



The data type associated with any map depends on the DATA 
specifications, or lack thereof, in both the DPHMSD and DFHMDI 
macro-^-djist ructions: 

1. A DATA operand in a DFHMDI macro will always override that 
in a DFHMSD macro. 

2. If no DATA operand is coded in the DFHMDI macro, the DATA 
operand in the DFHMSD macro will apply. 

3. If no DATA operand is coded in either macro, DATA=FIELD is 
the default. 

EXTATT= 

specifies whether the extended attributes (COLOR, HILIGHT, PS, 
and VALIDN) are supported. 

NO 

specifies that the extended attributes are not supported; 
the physical and symbolic description maps will be the same 
as those generated under Version 1 Release 4. "NO" is the 
default unless COLOR, HILIGHT, PS, or VALIDN is specified 
in the DFHMSD macro, in which case EXTATT=MAPONLY will be 
assumed. If the TERM operand is specified and is other 
than 3270, 3270-1, 3270-2, or ALL, EXTATT=MAPONLY or 
EXTATT=YES will be invalid, and the COLOR, HILIGHT, PS, and 
VALIDN operands on the DFHMSD, DFHMDI, and DFHMDF macros 
will be invalid. 

specifies that the extended attributes can be specified in 
a map, and that they can be modified dynamically. The 
symbolic description map (DSECT) will contain subfields for 
the attributes, identified by suffixes C (for COLOR), H 
(for HILIGHT) , P (for PS) , and V (for validation) . 

MAPONLY 

specifies that the extended attributes can be specified in 
a map, but that the resulting symbolic description map will 
contain no fields for them, and that it will be the same as 
one generated under Version 1, Release 4. This operand can 
be used to add the extended attributes to an existing map 
without recompiling the application program. 

HILIGHT= 

specifies the default highlighting attribute for all fields in 
all maps in a map set. 
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YES 



OFP 



is the default and means that no highlighting is used. 



BLINK 

specifies that the field is to "blink" at a set freguency. 

REVERSE 

specifies that the field is displayed in "reverse video", 
for example, on a 3278, black characters on a green 
background. 

UNDERLINE 

specifies that a field is underlined. 

If this option is specified when EXTATT=NO, a warning will be 
issued and the option ignored. If this option is specified, 
but EXTATT is not, EXTATT=MAPONLY will be assumed. 

HTAB=tab[ ,tab].. . 

specifies one or more tab positions for use with interactive 
and batch logical units having horizontal forms control. 



LANG= 



specifies the language in which the application program 
referring to a symbolic description map is written and, hence, 
is applicable for only a DFHMSD TYPE=DSECT macro instruction. 



ASM 



indicates that the symbolic description map is to be 
referred to by an assembler— language program. 



COBOL 

indicates that the symbolic description map is to be 
referred to by a COBOL program. 



PLI 



RPG 



indicates that the symbolic description map is to be 
referred to by a PL/I program. 



indicates that the symbolic description map is to be 
referred to by an RPG II program. This parameter is valid 
for CICS/DOS/VS only. 

LDC=mnemonic 

specifies the mnemonic to be used by CICS/VS to determine the 
logical device code that is to be used for a BMS output 
operation and transmitted in the function management header to 
the logical unit if no LDC operand has been specified on any 
previous BMS output in the logical message. This operand is 
used only for TCAM and VTAM— supported 3600 terminals, and batch 
logical units. 



M0DE= 



IN 



OUT 



indicates an input map generation. 



indicates an output map generation. 
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OBFMT= 



INOUT 

indicates that the map definition is to be used for both 
input and output mapping operations. 

Not e; Input mapping is not available for VTAM— supported 3600 
terminals. However, INOUT may be specified for map generation. 
The map can then be used as a dummy input map for input 
operations using the DFHBMS TYPE=IN macro instruction. 



specifies whether outboard formatting is to be used. This 
operand is available only for 3650 logical units. Refer to the 
CICS/YS 3650 Guide for details of 3650 logical units and of 
outboard formatting. 

YES 

indicates that all maps within this mapset are eligible for 
use in outboard formatting, except those for which OBFMT=NO 
is specified in the DFHMDI macro instruction. 



NO 



indicates that no maps within this mapset are eligible for 
use in outboard formatting, except those for which 
0BFMT=YES is specified in the DFHMDI macro instruction. 



PS = 



specifies that programmed symbols are to be used. 

BASE 

specifies that only the basic symbols are used. 

psid 

specifies a single EBCDIC character or a hexadecimal code 
on the form X^n 1 , that identifies the set of programmed 
symbols. 

If this option is specified when EXTATT=N0, a warning will be 
issued and the option ignored. If this option is specified, 
but EXTATT is not, EXTATT=MAPONLY will be assumed. 

ST0RAGE=AUT0 

• This operand is not valid for RPG programs. 

specifies, for COBOL programs, that the symbolic storage 
definitions of the maps in the map set are to be separate (that 
is, not redefined) areas. This operand is used when the 
symbolic storage definitions are copied into the WORKING- 
STORAGE section of a program using the command— level interface 
and the storage for the separate maps in the map set is to be 
used concurrently. (For information about the command— level 
interface, see the C ICS/VS Applications Programmer' s Re ference 
Manual (Comman d Level ) .) 

specifies, for PL/I programs, that the symbolic storage 
definitions are to be declared as having the AUTOMATIC storage 
class. If not specified, the symbolic storage definitions are 
declared as having the BASED storage class. 

specifies, for assemoler language programs, that separate maps 
within a map set are to occupy separate storage, not to overlay 
one another. 
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If STORAGB=AUTO is specified, BASE=nam3 cannot be used. 
STORAGE=AUTO is specified and TIOAPFX is not specified, 
TIOAPPX=YES is assumed. 



If 



SUFFIX =n 

specifies a one— character map set suffix that overrides any 
suffix implied by the TERM operand. A message will indicate 
that the TERM operand has been ignored. The user should 
catalog the map set, with this suffixed name, in the program 
library, and ensure also that there is no conflict with a 
generated name of another version of the map. The use of 
numeric suffixes would help prevent conflict. 

TERM=terminal type 

indicates the type of output device or logical unit associated 
with the map set. The parameters that may be coded after TERM- 
are given in the left— hand column of the table below. 



TERM= 



Remarks 



Map Set 
Suffix 



CRLP 

TAPE 

DISK 

TWX 

1050 

2740 

2741 

2770 

2780 

3780 

3270-1 

3270-2 

INTLU | 3767 | 37701 | SCS 



Card— Reader— In/Line— Printer-Out 



2980 

2980-4 

3270 



3601 
3653 

3650UP 
3650/3270 

BCHLO|377 0B 



ALL 



Use for 40— column displays 
Use for 80— column displays 
These four parameters are 
synonymous. They cover all 
interactive logical units, 
including the 3790 full- 
function LU and the 
SCS-printer LUs (3270 and 3790) , 
Excluding the 2980 Model 4 

For use when it is not 
important to distinguish 
between different models. 
This parameter is synonymous 
with ALL, and is the default 
applied if the operand is not 
coded. 

Use for the host— conversational 

(3653) LU 

Use for the interpreter LU 
Use for the host— conversational 

(3270) LU 

These two parameters are 
synonymous. They cover all 
batch and batch data inter- 
change logical units. 
Covers all the above 



blank 
U 

V 
W 



Y 
blank 
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TIOAPPX= 



For TCAM— connected terminals (other than 3270 or SNA devices), 
use either CRLP or ALL; for TCAM-connected 3270s or SNA 
devices, select the appropriate parameter in the normal way. 

The application programmer who specifies ALL in the TEEM 
operand must be certain that device— dependent characters are 
not included in the map set and must ensure that format 
characteristics such as page size are suitable for all 
input/output operations (and all terminals) in which the map 
set will be applied. For example, some terminals are limited 
to 480 bytes, others to 1920 bytes; the 3604 is limited to six 
lines of 40 characters each. Within these guidelines, use of 
ALL can offer important advantages. Since an assembly run is 
required for each map generation, a specification of ALL, 
indicating that one map is to be used for multiple terminals, 
can result in significant time and storage savings. 

However, better run— time performance for maps used by single 
terminal types will be achieved if the terminal type (rather 
than ALL) is specified in the TERM operand. Alternatively, the 
BMS support for device— dependent map sets can be left 
ungenerated by specifying BMSDDS=N0 in the DFHSG PR0GRAM=BMS 
system generation macro instruction. (See the CICS/VS System 
Programmer's Reference Manual for further details.) 



specifies whether BMS should include a filler in the symbolic 
TIOA description (s) to allow for the unused TIOA prefix. If 
this operand is coded, the same storage address may be used for 
TIOA BAR and the map base. 



| VALIDN= 



YES 



indicates that the filler should be included in the 
symbolic TIOA description (s) . This operand is ignored 
unless TYPE=DSECT is coded. If TIOAPFX=YES is coded, all 
maps within the map set have the filler, except when- 
TIOAPFX=NO is coded on the DFHHDI macro instruction. 
TIOAPFX=YES is the default where LANG=RPG. 



NO 



is the default (except for RPG) and indicates that the 
filler is not to be included. The filler may still be 
included for a specific map if TIOAPFX=YES is coded on the 
DFHMDI macro instruction. 

Note : In previous versions of CICS/VS, it has not been valid 
to code TI0APFX=YES for an assembler language application 
program. If this operand was coded in this way, CICS/VS 
disregarded it and applied the default specification 
(TIOAPFX=NO) . in CICS/VS Version 1.4, it is valid to code 
TI0APFX=YES for an assembler program: doing so will thus 
produce a different object program under CICS/VS 1.4 from that 
which would be produced under earlier versions. 



MOSTFILL 

specifies that the field must be filled completely with 
data. An attempt to move the cursor from the field before 
it has been filled, or to transmit data from an incomplete 
field, will raise the inhibit input condition. 
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MUSTEflTER 

specifies that data must be entered into the field. An 
attempt to move the cursor from an empty field will raise 
the inhibit input condition. 

VTAB=tab[ ,tab].. . 

specifies one or more tab positions for use with interactive 
and batch logical units having vertical forms control. 
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DEFINING A MAP (DFHMDI MACRO INSTRUCTION) 



The DFHMDI macro instruction is used to define a single map. It defines 
the size of the data to be mapped and its position within the input or 
output. When defining more than one map within a map set, the 
corresponding number of DFHMDI macro instructions must be used. If the 
maps are for use in a COBOL program, and STORAGE=A(JTO has been specified 
in the DFHMSD macro, they must be specified in descending size seguence 
(size refers to the generated 01 level COBOL data areas and not to the 
size of the map on the screen) . The format of the DFHMDI macro 
instruction is as follows: 




[ , COLOR = {DEFAULT | BLUE | RED | PINK | GREEN | TURQUOISE 
YELLOW | NEUTRAL} ] 
,C0LUMN= {number | NEXT | SAME} ] 
,CTRL= ([ PRINT ][ , {L40 | L64 | L80 | HONEOM} ] 

[ ,FREEKB ][ , ALARM ][ ,FRSET ]) ] 
, DAT A= {FIELD | BLOCK} ] 
,HEADER=YES] 

, HILIGHT= {OFF | BLINK | REVERSE | UNDERLINE} ] 
, JUSTIFY= ([ fLEFTt RIGHT} ][ , {FIRST | LAST} ]) ] 
,LINE= {number I NEXT I SAME} ] 
,OBFMT={YES|NO} ] 
,PS={BASE|psid} ] 
,SIZE= (line, column) ] 
,TIOAPFX={YES|NO} ] 
,TRAILER=YES] 
,VALIDN= ([ MUSTFILL ][ ,MUSTENTER ]) ] 



where: 



map 



is the one— to seven— character name of the map, to be specified 
in the MAP operand of any DFHBMS macro instruction that refers 
to the map. Note, however, that for RPG programs the map name 
must not exceed 5 characters. 



COLOR= 



COLUMN= 



specifies the default color for all fields in a map unless 
overridden explicitly by the COLOR operand of a DFHMDF macro. 
If this option is specified when EXTATT=N0, a warning will be 
issued and the option ignored. If this option is specified, 
but EXTATT is not, EXTATT=MAPONLY will be assumed. 



specifies the column in a line at which the map is to be 
placed, that is, it establishes the left or right map margin. 
The JUSTIFY specification controls whether map and page margin 
selection and column counting are to be done with reference to 
the left or right side of the page. The columns between the 
specified map margin and the page margin are not available for 
subseguent use on the page for any lines included in the map. 

number 

is the column from the left or right page margin where the 
left or right map margin is to be established. 
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CTRL= 



NEXT 

indicates that the left or right map margin is to be placed 
in the next available column from the left or right on the 
current line. 

SAME 

indicates that the left or right map margin is to be 
established in the same column as the last map used that 
specified C0L0MN=number and the same JUSTIFY parameters as 
this macro instruction. 

Refer to the section "Map Positioning," later in this chapter, 
for a more detailed discussion. 



is used to specify device characteristics related to terminals 
of the 3270 Information Display System. CTRL=ALARM is valid 
for TCAM SNA 3270 SDLC and VTAM-supported terminals (except 
interactive and batch logical units) ; all other parameters for 
CTRL are ignored. To be effective, this operand must be 
specified on the last (or only) map of a page unless the CTRL 
operand of the DFHBMS macro is being used to override the 
corresponding operand in the DFHMSD macro. If the CTRL operand 
is specified in the DFHMDI macro, it cannot be specified in the 
DFHMSD macro. 

PRINT 

must be specified if the printer is to be started; if 
omitted, the data is sent to the printer buffer but is not 
printed. This operand is ignored if the BMS output reguest 
is directed to a 3270 display without the Printer Adapter 
feature • 

L40, L64, L80, HONEOM 

are mutually exclusive options that control the line length 
on the printer. L40, L64, and L80 force a carrier 
return/line feed after 40, 64, or 80 characters, 
respectively. HONEOM causes the default line printer 
length to be used . 

FREEKB 

specifies that the keyboard should be unlocked after this 
map is written out. If omitted, the keyboard remains 
locked; further data entry from the keyboard is inhibited 
until this status is changed. 

ALARM 

activates the 3270 audible alarm feature. For a VTAM 
terminal, ALARM signals BMS to set the alarm flag in the 
function management header; this feature is not applicable 
to interactive and batch logical units. 

FRSET 

indicates that the modified data tags (MDTs) of all fields 
currently in the 3270 buffer are to be reset to a not- 
modified condition (that is, field reset) before any map 
data is written to the buffer. This allows the DFHMDF 
ATTRB specification for the reguested map to control the 
final status of any fields written or rewritten in response 
to a DFHBMS macro instruction. 
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DATA= 

specifies the format of the data as seen by the application 
program . 

FIELD 

indicates that the data is passed as contiguous fields in 
the following format: 

|LL|A|data field | LL| A | data field |LL|A|etc. 

i 



LL is two bytes specifying the length of the data as input 
from the terminal (this field is ignored in output 
processing) . A is a byte into which the programmer may 
place an attribute to override that specified in the map 
used to process this data. (See "Standard Attribute List 
and Printer Control Characters (DFHBMSCA)," later in this 
chapter. ) 

BLOCK 

indicates that the data is passed as a continuous stream 
which is processed as line segments of the length specified 
in the map used to process this data set. The data is in 
the form that it appears on the terminal; that is, it 
contains data fields and interspersed blanks corresponding 
to any spaces that are to appear between the fields on 
output. The first byte of each line is the attribute byte; 
it is not available for data. 

| A | data field | space | A | data field | space | A | data field | etc 

i 



A DATA specification in a DFHMDI macro instruction overrides a 
DATA specification in a DFHMSD macro instruction. 

HBADER=YES 

allows this map to be used during PAGEBLD overflow without 
terminating the overflow condition (see "PAGEBLD Overflow 
Processing," later in this chapter). This operand may be 
specified for more than one map in a map set. 



HILIGHT= 



specifies the default highlighting attribute for all fields in 
a map. 

OFF 

is the default and means that no highlighting is used. 

BLINK 

specifies that the field is to "blink" at a set freguency. 

REVERSE 

specifies that the field is displayed in "reverse video", 
for example, on a 3278, black characters on a green 
background. 
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UNDERLINE 

specifies that a field is underlined. 

If this option is specified when EXTATT=NO, a warning will be 
issued and the option ignored. If this option is specified, 
but EXTATT is not, EXTATT=MAPONLY will be assumed. 



JUSTIFY= 



describes the margins on a page in which a map is to be 
formatted. 



LINE= 



LEFT 

indicates that the map is to be positioned starting at the 
specified column from the left margin on the specified 
line. 

RIGHT 

indicates that the map is to be positioned starting at the 
specified column from the right margin on the specified 
line. 

FIRST 

indicates that the map is to be positioned as the first map 
on a new page. Any partially formatted page from preceding 
DFHBMS requests is considered to be complete. This operand 
can be specified for only one map per page. 

LAST 

indicates that the map is to be positioned at the bottom of 
the current page. This operand can be specified for 
multiple maps to be placed on one page. However, maps 
other than the first map for which it is specified must be 
able to be positioned horizontally without requiring that 
more lines be used. 

LEFT and RIGHT are mutually exclusive, as are FIRST and LAST. 
If neither LEFT nor RIGHT is specified, LEFT is assumed. If 
neither FIRST nor LAST is specified, the data is mapped at the 
next available position as determined by other parameters of 
the map definition and the current mapping operation. FIRST 
and LAST are ignored unless PAGEBLD is specified, since 
otherwise only one map is placed on each page. 

Refer to the section "Map Positioning," later in this chapter, 
for a more detailed discussion. 



specifies the starting line on a page in which data for a map 
is to be formatted. 

number 

is a value from 1 to 240, indicating a starting line 
number. A request to map data on a line and column that 
has been formatted in response to a preceding request 
causes the current page to be treated as though complete. 
The new data is formatted at the requested line and column 
on a new page. 



NEXT 



indicates that formatting of data is to begin on the next 
available completely empty line. If LINE=NEXT is specified 
in the DFHMDI macro, it is ignored for input operations and 
LINE=1 is assumed. 
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OBFMT= 



PS= 



SIZE= 



SAME 

indicates that formatting of data is to begin on the same 
line as that used for a preceding DFHBMS request. If the 
data does not fit on the same line, it is placed on the 
next available completely-empty line. 

Refer to the section "Map Positioning," later in this chapter, 
for a more detailed discussion. 



specifies whether outboard formatting is to be used. This 
operand is available only for 3650 logical units. Refer to the 
CICS/VS 3650 Guide for details of 3650 logical units and of 
outboard formatting. 

If OBFMT is not coded in the DFHMDI macro instruction, the 
OBFMT specification in the DFHMSD macro instruction is used. 

YES 

indicates that this map is to be used with outboard 
formatting. 

NO 

indicates that this map is not to be used with outboard 
formatting. 



specifies that programmed symbols are to be used. 

BASE 

specifies that only the basic symbols are used. 

psid 

specifies a single EBCDIC character or a hexadecimal code 
on the form X»nn", that identifies the set of programmed 
symbols. 

If this option is specified when EXTATT=N0 , a warning will be 
issued and the option ignored. If this option is specified, 
but EXTATT is not, EXTATT=MAPONLY will be assumed. 



gives the dimensions of a map in terms of length and width. 

line 

is a value from 1 to 240, indicating the length of a map as 
a number of lines. 

column 

is a value from 1 to 240, indicating the width of a map as 
a number of characters per line. Space for the attribute 
byte should be included in the column specification. 

The SIZE operand is required in the following cases: 

• A P0S= (line, column) specification is given in a DFHMDF 
macro instruction defining a specific field within this 
map. 

• This map is to be referred to in a DFHBMS TYPE=PAGEBLD 
macro instruction. 
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TI0APPX= 



This map is to be used when referring to input data from 
other than a 3270 terminal in a DPHBMS TYPE=IN or DFHBMS 
TYPE=MAP macro instruction. 



specifies whether or not BMS should include a filler in the 
symbolic TIOA description to allow for the unused TIOA prefix. 
If this operand is coded, the same storage address may be used 
for TIOABAR and the map base. If this operand is not coded, 
the TIOAPFX specification derived from the DFHMSD macro is 
used. 



YES 



NO 



indicates that the filler should be included in the 
symbolic TIOA description for this map. This operand is 
ignored unless TYPE=DSECT is coded on the DFHMSD macro 
instruction . 



indicates the filler is not to be included for this map, 



Note ; In previous versions of CICS/VS, it has not been valid 
to code TIOAPFX=YES for an assembler language application 
program. If this operand was coded in this way, CICS/VS 
disregarded it and applied the default specification 
(TIOAPFX=NO) . In CICS/VS Version 1.4, it is valid to code 
TIOAPFX=YES for an assembler program: doing so will thus 
produce a different object program under CICS/VS 1.4 from that 
which would be produced under earlier versions. 

TRAILER=YES 

allows this map to be used during PAGEBLD overflow without 
terminating the overflow condition (see "PAGEBLD Overflow 
Processing," later in this chapter) . This operand may be 
specified for more than one map in a map set. If a trailer map 
is used other than in the overflow environment, the space 
normally reserved for overflow trailer maps is not reserved 
while mapping the trailer map. 



| VALIDN= 



MUSTFILL 

specifies that the field must be filled completely with 
data. An attempt to move the cursor from the field before 
it has been filled, or to transmit data from an incomplete 
field, will raise the inhibit input condition. 

MUSTENTER 

specifies that data must be entered into the field. An 
attempt to move the cursor from an empty field will raise 
the inhibit input condition. 
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DEFINING A FIELD (DFHMDF MACRO INSTRUCTION) 

The DFHMDF macro instruction is used to define one field in a map. One 
DFHMDF macro instruction is required for each field, giving information 
such as symbolic field name, field position, field length, attribute 
byte (for 3270 terminals), initial constant data, justification of 
input, and COBOL or PL/I data picture. 

The maximum number of named fields that can be defined for a COBOL or 
| PL/I input/output map is 1023: 

The format of the macro instruction is as follows: 



,P0S= {number | (line, column) } ] 

,ATTRB=([ {ASKIP|PROT|UNPROT[ ,NUM]} ][ , {BRT| NORM | DHK} ] 

[,DET][,IC][,FSET]) ] 
,COLOR= ( DEFAU LT! BLUE |RED |PINK | GREEN | TURQUOISE | 

YELLOW | NEUTRAL} ] 
,GRPNAME=group— name ] 

,HILIGHT=f OFF | BLINK IREVERSE IUNDERLINB} ] 
,INITIAL= , character data' |XINIT=hexadecimal data] 
,JUSTIFY=([ {LEFT|RIGHT} ][ , {BLANK| ZERO} ]) ] 
,LENGTH=number ] 
,OCCURS=number ] 
,PICIN= , value» ] 
,PICOUT= "value* ] 
,PS={BASE|psid} ] 
, VALIDN= ([ MUSTFILL ][ ,MUSTENTER ]) ] 




where 
fid 



is the one— to seven-character name of the field, used as a 
symbolic reference to the field by the application program. 
Note, however, that for RPG programs, the field name must never 
exceed 5 characters, and if OCCURS= is specified, the field 
name must not exceed 3 characters. 

Although specification of a field name is not required for 
every field within a map, a field name must be specified for at 
least one field of any map to be compiled under COBOL or PL/I. 
All fields within a group must have names. 

If no name is specified for a field, an application program 
cannot access the field map to change its attributes or alter 
its contents. For an output map, omitting the field name may 
be appropriate when the INITIAL operand is used to specify 
field contents. If a field name is specified and the map that 
includes the field is used in a mapping operation, any data 
supplied by the user overlays data supplied by initialization 
(unless DATA=NO is specified or assumed by default). 
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POS = 



is used to specify the individually addressable character 
location in a map at which the attribute byte that precedes 
this field is positioned. Specification of the DFHMDF macro 
instruction must be sequenced by the POS operand except for 
output mapping operations using DATA^FIBLD. 

The POS operand defines the location of fields in a map. The 
location of data on the output medium is dependent on DFHMDI 
macro parameters as well. 

For each field definition (DFHMDF macro instruction) , the first 
position is reserved for an attribute byte. When supplying 
data for input mapping from non— 3270 devices, the actual input 
data must allow space for this attribute byte. Input data must 
not start in column 1 but may start in column 2. 

The POS operand always contains the location of the first 
position in a field, which is normally the attribute byte when 
communicating with the 3270. For the second and subsequent 
fields of a group, the POS operand points to an assumed 
attribute— byte position, ahead of the start of the data, even 
though no actual attribute byte is necessary. If the fields 
follow on immediately from one another, the POS operand should 
point to the last character position in the previous field in 
the group. 

When a position number is coded which represents the last 
character position in the 32.70, then two special rules apply: 

• The IC attribute should not be coded on that DFHMDF macro. 
The cursor may be set to location zero by using the cursor 
operand of the DFHBMS macro. 

• If the field is to be used in an output mapping operation 
with the DATA=0NLI specification, an attribute byte for 
that field must be supplied in the TIOA by the application 
program . 

number 

is an absolute displacement (relative to zero) from the 
beginning of the map being defined. 

(line, column) 

are line and column specifications (relative to one) within 
the map being defined. 
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ATTRB= 



is applicable only to fields to be displayed on a 3270 and 
specifies device-dependent characteristics and attributes, such 
as the capability of a field to receive data or the intensity 
to be used when the field is output. If the ATTRB operand is 
specified within a group of fields, it must be specified in the 
first field entry. A group of fields appears as one field to 
the 3270. Therefore, the ATTRB specification refers to all of 
the fields in a group as one field rather than as individual 
fields. (Refer to the IBM 3270 Information Display System 
Component Description for a full explanation of the effects of 
the attribute byte settings.) 

This operand applies only to 3270 data stream devices; it will 
be ignored for other devices, including the SCS Printer Logical 
Unit. It will also be ignored if PR0PT=NLE0M is specified on 
the DFHBMS TYPE=PAGEBLD macro for transmission to a 3270 
printer. In particular, ATTRB=DRK should not be used as a 
method of protecting secure data on output. It could, however, 
be used for making an input field non— display for secure entry 
of a password from a screen. 

For input map fields, DET and NUM are the only valid options; 
all others are ignored. 

ASKIP 

indicates that data cannot be keyed into the field and 
causes the cursor (current location pointer) to 
automatically skip over the field. 

PROT 

indicates that data cannot be keyed into the field. 

If data is to be copied from one device to another attached 
to the same 3270 control unit, the first position (address 
0) in the buffer of the device to be copied from must not 
contain an attribute byte for a protected field. When 
preparing maps for 3270s, ensure that the first map of any 
page does not contain a protected field starting at 
position 0. Refer to the publication IBM 3270 Information 
Dis pla y Sys t em Component Description for further 
information. 

UNPROT 

indicates that data can be keyed into the field. 



NUM 



ensures that the data entry keyboard is set to numeric 
shift for this field unless the operator presses the alpha 
shift key, and prevents entry of nonnumeric data if the 
Keyboard Numeric Lock feature is installed. 



BRT 



specifies that a high— intensity display of the field is 
I required. By virtue of the 3270 attribute character bit 

| assignments, a field specified as BRT is also potentially 

| detectable. However, for the field to be recognized as 

| detectable by BMS, DET must also be specified. 

NORM 

specifies that the field intensity is to be normal. 



DRK 



specifies that the field is nonprint/nondisplay . DRK 
cannot be specified if DET is specified. 
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DET 

specifies that the field is potentially detectable. 

The first character of a 3270 detectable field must be a 
"?", n > n , "&", or blank. If the first character is »&•• or 
blank, the field is an attention field; if the first 
character is "?" or ">" , the field is a selection field. 
(See the publication IBM 3270 Information Display System 
Comp one nt Descripti on for further details of detectable 
fields.) 

A field for which BRT is specified is potentially 
| detectable to the 3270, by virtue of the 3270 attribute 

| character bit assignments, but is not recognized as such by 

BMS unless DET is also specified. 

DET and DRK are mutually exclusive options. 

| If DET is specified for an input field, only one data byte 

is reserved for each input field. This byte is set to 
| X^OO', and remains unchanged if the field is not selected. 

| If the field is selected the byte is set to X'FF 1 . 

No other data is supplied, even if the field is a selection 
field and the ENTER key has been pressed. 

If the data in a detectable field is required, all of the 
following conditions must be fulfilled: 

1. The field must begin with either a »?«• ">", or 
"&" and DET must be specified in the output map. 

2. The ENTER key (or some other attention key) must be 
pressed after the field has been selected, although for 
detectable fields beginning with "&" the ENTER key is 
not required. 

3. DET must not be specified for the field in the input 
map. DET must, however, be specified in the output 
map. 



IC 



indicates that the cursor is to be placed in the first 
position of this field. The IC attribute for the last 
field for which it is specified in a map is the one that 
takes effect. If not specified for any fields in a map, 
the default location is zero. Specifying IC with ASKIP or 
PROT causes the cursor to be placed in an unkeyable field. 

This option may be overridden by specifying the CURSOR 
operand for the BMS request that causes the write 
operation. See the descriptions of the DFHBMS 
TYPE=PAGEBLD, TEXTBLD, and OUT macros, later in this 
chapter. 
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FSET 

specifies that the modified data tag (MDT) for this field 
should be set when the field is sent to a terminal. 

Specification of FSET causes the 3270 to treat the field as 
though it has been modified. On a subsequent read from the 
terminal, this field is read, whether or not it has been 
modified. The MDT remains set until the field is rewritten 
without ATTRB=FSET or until an output mapping request (for 
example, DFHMSD CTRL=FRSET or DFHBMS CTRL=FRSET) causes the 
MDT to be reset. 

Either of two sets of defaults may apply when a field to be 
displayed on a 3270 is being defined but not all parameters are 
specified. If no ATTRB parameters are specified, ASKIP and 
NORM are assumed. If any parameter is specified, UNPROT and 
NORM are assumed for that field unless overridden by a 
specified parameter. 



COLOR= 



specifies the color to be used. If this option is specified 
when EXTATT=NO, a warning will be issued and the option 
ignored. If this option is specified, but EXTATT is not, 
EXTATT=MAPONLY will be assumed. 

GRPNAME=group name 

is the name used to generate symbolic storage definitions and 
to combine specific fields under one group name. The group 
name has a maximum length of five characters for RPG II 
programs, and seven characters for other languages. The same 
group name must be specified for each field that is to belong 
to the group. The fields in a group must follow on; there can 
be intervening gaps between them, but not other fields from 
outside the group. A field name must be specified for every 
field that belongs to the group, and the POS operand must be 
also specified to ensure the fields follow each other. 

All the DFHMDF macros defining the fields of a group must be 
placed together, and in the correct order (upward numeric order 
of the POS operand). For example, the first 20 columns of the 
first six lines of a map can be defined as a group of six 
fields, so long as the remaining columns on the first five 
lines are not defined as fields. 

The ATTRB= operand specified on the first field of the group 
applies to all of the fields within the group. The lengths of 
the fields within the group must not collectively exceed 256 
bytes. If this operand is specified, the OCCURS operand cannot 
be specified. 

Appendix B contains examples showing, amongst other things, the 
effect of the GRPNAME operand. 



HILIGHT= 



specifies the type of highlighting to be used. 

OFF 

is the default and means that no highlighting is used. 

BLINK 

specifies that the field is to "blink" at a sat frequency. 



Chapter 4.3. Basic Mapping Support 269 



REVERSE 

specifies that the field is displayed in "reverse video", 
for example, on a 3278, black characters on a green 
background. 

UNDERLINE 

specifies that a field is underlined. 

If this option is specified when EXTATT=NO, a warning will be 
issued and the option ignored. If this option is specified, 
but EXTATT is not, EXTATT=MAPONLY will be assumed. 

INITIAL =I character data* | XINIT=hexadecimal data 

is used to specify constant or default data for an output 
field. The INITIAL operand is used to specify data in 
character form; the XINIT operand is used to specify data in 
hexadecimal form. INITIAL and XINIT are mutually exclusive. 

For fields with the DET attribute, initial data that begins 
with a blank character, "&", ">", or "?" should be supplied. 

The number of characters that can be specified in the INITIAL 
operand is restricted to the continuation limitation of the 
assembler to be used or to the value specified in the LENGTH 
operand (whichever is the smaller J . 

Hexadecimal data is written as an even number of hexadecimal 
digits, for example, XINIT=C1C2. If the number of valid 
characters is smaller than the field length, the data will be 
padded on the right with blanks. For example, XINIT=C1C2 might 
result in an initial field of »AB •. 

If hexadecimal data is specified that corresponds with line or 
format control characters, the results will be unpredictable. 
The XINIT operand should therefore be used with care. 



JUSTIFY= 



indicates the field justifications for input operations. This 
operand is ignored for TCAM-supported 3600 and 3790, and for 
VTAM— supported 3600, 3650, and 3790 terminals, as input mapping 
is not available. 

LEFT 

specifies that data in the input field is left— justified. 

RIGHT 

specifies that data in the input field is right— justified. 

BLANK 

specifies that blanks are to be inserted in any unfilled 
positions in an input field. 

ZERO 

specifies that zeros are to be inserted in any unfilled 
positions in an input field. 

LEFT and RIGHT are mutually exclusive, as are BLANK and ZERO. 
If certain parameters are specified but others are not, 
assumptions are made as follows: 
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Specified Assumed 

LEFT BLANK 

RIGHT ZERO 

BLANK LEFT 

ZERO RIGHT 

If JUSTIFY is omitted, but the NUH attribute is specified, 
RIGHT and ZERO are assumed. If JUSTIFY is omitted, but 
attributes other than NUM are specified, LEFT and BLANK are 
assumed . 

Note ; If a field is initialized by an output map or contains 
data from any other source, data that is keyed as input may not 
be justified and the additional data may remain in the field. 

LENGTH=number 

indicates the length (from 1 to 256 bytes) of this field. This 
specified length should be the maximum length reguired for 
application— program data to be entered into the field; it 
should not include the one— byte attribute indicator appended to 
the field by CICS/VS for use in subseguent processing. The sum 
of the lengths of the fields within a group must not exceed 256 
bytes. LENGTH can be omitted if PICIN or PICOUT is specified 
but is reguired otherwise. 

The map dimensions specified in the SIZE operand of the DFHMDI 
macro instruction defining a map may be smaller than the actual 
page size or screen size as defined for the terminal. The 
LENGTH specification in a DFHMDF macro instruction cannot cause 
the map-defined boundary on the same line to be exceeded. That 
is, the length declared for a field- cannot exceed the number of 
positions available from the starting position of the field to 
the final position of the map— defined line. For example, given 
an 80— position page line, the following map definition and 
field definition are valid: 

DFHMDI SIZE= (2,40), ... 
DFHMDF P0S=22,LENGTH=17, ... 

but the following definitions are not acceptable: 

DFHMDI SIZE= (2,40), ... 
DFHMDF POS=22,LENGTH=30,... 

OCCURS=number 

specifies that the indicated number of entries for the field 
are to be generated in a map and that the map definition is to 
be generated in such a way that the fields are addressable as 
entries in a matrix or an array. This permits several data 
fields to be addressed by the same name (subscripted, of 
course) without generating a unigue name for each field. 
OCCURS and GRPNAME are mutually exclusive; that is, OCCURS 
cannot be used when fields have been defined under a group 
name. If this operand is omitted, a value of 1 is assumed. 

Appendix B contains examples showing, amongst other things, the 
effect of the OCCURS operand. 
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PICIN= 'value* 

specifies a picture to be applied to an input field in an IN or 
INOUT map; this picture serves as an editing specification 
which is passed to the application program, thus permitting the 
user to exploit the editing capabilities of COBOL or PL/I. The 
PICIN operand is not valid for assembler or RPG programs. BMS 
checks •value 1 to ascertain that the specified characters are 
valid picture specification characters for the language of the 
map. However, no validity checking of the input data is 
performed by BMS or the high— level language when the map is 
used, so any desired checking must be performed by the 
application program. The length of the data associated with 
•value* should be the same as that specified in the LENGTH 
operand if LENGTH is specified. If both PICIN and PICOUT (see 
below) are used, an error message is produced if their 
calculated lengths do not agree; the shorter of the two lengths 
is used. If PICIN or PICODT is not coded for the field 
definition, a character definition of the field is 
automatically generated regardless of other operands that are 
coded, such as ATTRB=NUM. 

As an example, assume the following map definition is created 
for reference by a COBOL application program: 

TYPE=DSECT,LANG=COBOL,MODE=INOUT 
LINE=1,C0LUMN=1 ,SIZE= (1 ,80) 
POS=0,LENGTH=30 

POS=40,LENGTH=10,PICOUT=»$$$,$$0.00» 
POS=60 ,LENGTH=6 ,PICIN= , 9999V99« ,PICOOT= »ZZ9 .99' 
DFHMSD TYPE=FINAL 

The following DSECT is generated: 
01 



MAPX 


DFHMSD 


HAP 


DFHMDI 


F1 


DFHMDF 


P2 


DFHMDF 


F3 


DFHMDF 



01 



MAPI. 




02 


F1L 


COMP PIC S9(4) . 


02 


F1A 


PICTORE X. 


02 


FILLER 


REDEFINES F1A. 


03 


F1F 


PICTURE X. 


02 


F1I 


PIC X (30) . 


02 


FILLER 


PIC X. 


02 


F2L 


COMP PIC S9 (4) . 


02 


F2A 


PICTURE X. 


02 


FILLER 


REDEFINES F2A . 


03 


F2F 


PICTURE X. 


02 


F2I 


PIC X(10) . 


02 


FILLER 


PIC X. 


02 


F3L 


COMP PIC S9 (4). 


02 


F3A 


PICTURE X. 


02 


FILLER 


REDEFINES F3A. 


03 


F3F 


PICTURE X. 


02 


F3I 


PIC 9999V99. 


02 


FILLER 


PIC X. 


MAPO REDEFINES MAPI. 


02 


FILLER 


PICTURE X (3) . 


02 


F10 


PIC X (30 ) . 


02 


FILLER 


PIC X. 


02 


FILLER 


PICTURE X(3) . 


02 


F20 


PIC $$$,$$0.00. 


02 


FILLER 


PIC X. 


02 


FILLER 


PICTURE X(3) . 


02 


F30 


PIC ZZ9.99. 


02 


FILLER 


PIC X. 
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PICOUT=» value* 

is similar to PICIN, except that a picture to be applied to an 
output field in the OUT or INOOT map is generated. 

Like PICIN, PICOUT is not valid for assembler or RPG programs. 



PS = 



VALIDN= 



specifies the programmed symbol set to be used for the display 
of the field. 

BASE 

specifies that only the basic symbols are used. 

psid 

specifies a single EBCDIC character or a hexadecimal code 
on the form X^nn 1 , that identifies the set of programmed 
symbols. 

If this option is specified when EXTATT=NO, a warning will be 
issued and the option ignored. If this option is specified, 
but EXTATT is not, EXTATT=MAPONLY will be assumed. 



MOSTFILL 

specifies that the field must be filled completely with 
data. An attempt to move the cursor from the field before 
it has been filled, or to transmit data from an incomplete 
field, will raise the inhibit input condition. 

MUSTENTER 

specifies that data must be entered into the field. An 
attempt to move the cursor from an empty field will raise 
the inhibit input condition. 
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Input and Output Operations Using the BMS Macro Instructions 

Input and output operations using the facilities of BMS are requested by 
issuing DFHBMS macro instructions. Parameters provided by the 
application program indicate whether an input or an output operation is 
needed, the name of the map to be used by BMS, and other information to 
control the mapping function. Control is passed to BMS, which performs 
any required input/output operations through terminal control. 

Initial terminal input, which causes a task to be initiated, is 
stored in the initial TIOA of the task as a native— mode data stream. 
The initial input data can be mapped into a particular format by issuing 
a DFHBMS TYPE=MAP macro. The format of this initial input data must 
correspond to that of the requested map. Input data to be mapped from a 
3270 must contain 3270 device— dependent code (in particular, the data 
stream must contain an SBA) . Similarly, the DFHBMS TYPE=MAP macro can 
be used to map further input data, obtained by means of a terminal 
control READ request, into a particular format. 

Alternatively, the DFHBMS TIPE=IN macro can be issued; this macro 
causes a terminal control READ/WAIT operation to occur, and the 
resulting terminal input is mapped into a particular format. The data 
returned from an input mapping operation is in TIOA format. The address 
of the TIOA containing the mapped data is placed in TCTTEDA for a 
TTPE=IN operation; for a TYPE=MAP operation, or an output operation, the 
address will be placed in the location (TCTTEDA or TCAMSIOA) used to 
specify the input data area. (See the section, "Addressing Input/Output 
Areas," below, for details of specifying input data areas.) 

For an output mapping operation, if data is to be passed from the 
TIOA of an application program, the application program must have 
obtained, through storage control, a TIOA large enough to contain the 
symbolic storage definition of the map being used. Any fields for which 
data is not to be passed to the mapping operation must be set to nulls 
(X^OO 1 ) ; this is best achieved through use of the INITIMG=00 operand of 
the DFHSC TYPE=GETMAIN macro instruction. The first position of a field 
to be sent must not contain a null; if it does, the field will be 
ignored. 

Maps are defined in a map set, which permits the formatting of a page 
of output using one or more of the maps in the map set. If the map set 
has been placed in the CICS/VS program library, the user should specify 
MAPSET=map— set— name and MAP=map— name in any DFHBMS macro instruction 
requesting an operation in which the map is required. If preferred, the 
user may place the seven— character name of the map set at TCAMSMSN and 
the name of the map at TCABMSMN; the MAPSET=IES and MAP=YES operands 
inform BMS that the names have been supplied in this way. (Note : Map 
sets did not exist in pre— VS BMS. For pre— VS application programs, BMS 
takes the name of the map to be the name of the map set.) 



Implied READ/WRITE 

DFHBMS TYPE=IN or TYPE=0UT macro instructions result in a terminal 
control READ or WRITE, respectively. Therefore, the user does not need 
to code any terminal control (DFHTC) macro instructions. 

However, nothing prevents the user from intermingling native— mode and 
BMS operations. A DFHBMS TYPE=MAP instruction can be used to format a 
native— mode input TIOA. If a MAP operation is requested for input from 
an unformatted 3270 buffer, mapping is not performed and the unformatted 
native— mode TIOA is returned to the application program. 
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It is nevertheless possible to use DFHBMS TYPE=MAP for the TIOA 
containing a transaction— initiating data stream. All that is necessary 
to do so is to format the screen with the preceding task. 



A ddressing In put /O ut put .A reas 

Before a task issues a DFHBMS TYPE=MAP, or any BMS output macro, the 
address of the data being passed must be set up in either TCTTEDA or 
TCAMSIOA. The rules for deciding which area to use are: 

• If the task is not terminal— oriented, the address of the TIOA— like 
area being used must be put in TCAMSIOA. TCTTEDA cannot be 
referenced as the task has no TCTTE. 

• If the task is terminal-oriented, but a TIOA is not being used, the 
address of the TIOA— like area containing the user data must be put 
into TCAMSIOA and TCTTEDA must be filled with binary zeros. 

• If the task is terminal-oriented and the data is in a TIOA, the 
address of the TIOA may be put into either TCTTEDA or TCAMSIOA. If 
the address is put into TCAMSIOA, TCTTEDA must be filled with 
binary zeros. If the address is put into both TCTTEDA and 
TCAMSIOA, the address in TCTTEDA is used. 

TCTTEDA is altered by BMS; the user must not assume that its contents 
are unchanged. 

A BMS input operation places the data into a TIOA, and the address of 
the TIOA is returned in TCTTEDA. 

Terminal-oriented tasks need not use actual TIOAs. Any task may pass 
data to BMS in any portion of dynamically acquired storage which looks 
like a TIOA in all respects except two: 

© The storage class need not be terminal. 

© The storage chain address need not refer to a TCTTE or other 
terminal storage. 



I Non— Terminal-Oriented Tasks 
I 

| These tasks do not have a TIOA or a TCTTE; therefore such tasks cannot 
| issue any BMS macro instructions that use information in these areas. 
| They can issue only DFHBMS TYPE=ROUTE, DFHBMS TYPE=PAGEBLD with a 
| disposition of STORE or RETURN, and DFHBMS TYPE=TEXTBLD with a 
| disposition of STORE or RETURN. 



T echnique for Sett ing TCT TED A to Bina ry Ze ros i n PL/I 

The NULL built— in function cannot be used to set TCTTEDA to binary zeros 
because this places hexadecimal 'FF 1 in the high— order byte of the 
address. Instead, the following statement can be used: 

UNSPEC (TCTTEDA) =32 '(MB; 
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DFHBMS Macro Instruction s 

BMS macro instructions are provided to enable the application programmer 
to: 

Map data that is already in a TIOA (without any terminal I/O taking 
place) (DFHBMS TYPE=MAP) 

Read in and map data from a terminal (DFHBMS TYPE=IN) 

Cumulatively build one or more pages of output data using maps 
(DFHBMS TYPE=PAGEBLD) 

Cumulatively build one or more pages of output data without using 
maps (DFHBMS TYPE=TEXTBLD) 

Terminate the accumulation of output data that has been logically 
combined and write it to an output device (DFHBMS TYPE=PAGEOUT) 

Write data (without accumulation) to an output device (DFHBMS 
TYPE=OUT) 

Discontinue the process of building a logical message (DFHBMS 
TYPE=PURGE) 

Define the terminal (s) or operator (s) that are to receive an output 
message (DFHBMS TYPE=ROUTE) 

Check the response to a BMS request (DFHBMS TYPE=CHECK) 

In the sections that follow, the syntax of each type of DFHBMS macro 
is shown , and the use of the macro is explained. Parameters of the 
TYPE= operand are discussed separately under each macro. Descriptions 
of all other operands for the DFHBMS macros are gathered into a single 
section, arranged in alphabetical order, at the end of the chapter. 



O utput Operation s 

There are a variety of ways in which the various DFHBMS macros can be 
used, and combined, for output operations. 

The simplest case is DFHBMS TYPE=OUT (without PAGEBLD or TEXTBLD) . 
This macro instruction results in a simple output operation similar to 
that resulting from a DFHTC TYPE=WRITE macro, but with a mapping 
operation probably, but not necessarily, included. 

When an application programmer wishes to output data which may occupy 
more than one device output buffer he can build a single logical message 
using a series of DFHBMS TYPE=PAGEBLD macros (if he wants mapping to be 
included) or DFHBMS TYPE=TEXTBLD (if mapping is not required). When the 
logical message is complete, he terminates the process of accumulation 
and causes physical output to occur by issuing a DFHBMS TYPE=PAGEOUT 
macro . 

The DFHBMS TYPE=ROUTE macro does not itself cause any output 
operation to occur; it defines the destination for ensuing BMS output 
macros. The effect of a ROUTE macro should be terminated by a PAGEOUT 
macro before another ROUTE macro is issued. 

Output operations that do not send user-supplied data (TYPE=PAGEBLD, 
DATA=NO or TYPE=OUT, DATA=NO) do not require TIOAs. 
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Input Mapping without I/O (TYPE=MAP) 



To request that data already in an input TIOA is mapped according to a 
specified map. 



1 1 

| IDFHBMS 


i 

TYPE=(MAP[ ,SAVE]) | 




[ , MAP= {map-name | YES} ]|[ ,MAPADR= {symbolic-address | YES} ]| 




[ ,MAPSET= {mapset-name |YES} ]| [ ,MSETADR= | 




{symbolic— address | YES} ] | 




[ ,ERROR=symbolic-address] | 




[ ,INVMPSZ=symbolic— address] | 




[ / MAPFAIL=symbolic— address] | 


■ i 


[ ,NORESP=symbolic-address] | 

- - - ■- - - » 



TYPE=MAP 



specifies an input mapping operation without any associated 
terminal I/O operation. The application program must have 
placed the address of an input TIOA containing data to be 
mapped into TCTTEDA or TCAMSIOA. The data in the TIOA is 
positioned into a new TIOA using the map specified in the MAP 
operand of the DPHBMS macro instruction, but no terminal I/O 
operation occurs. An example of such a TIOA is the initial 
TIOA given to a transaction upon entering a transaction code. 
If data is included with the transaction code, the screen must 
have been formatted previously by another transaction, or the 
data is not mapped. The address of the new TIOA is returned to 
the application program in the location in which the original 
data area was specified (TCTTEDA or TCAMSIOA) . 

The following types of data are not mapped, but are left in the 
TIOA unaltered. 

• data from TCAM-supported 3600 or 3790 

• data from VTAM-supported 3600 or 3650 (except 3650 host 
conversation (3270) logical unit) 

© data from 3790 

• word processing data streams, that is, data received from a 
word processing medium type 1, 2, 3 or 4. 



SAVE 



When used with MAP, SAVE specifies that the user-nsupplied data 
area addressed by TCTTEDA or TCAMSIOA is not to be altered, and 
that a new TIOA is to be acquired for the operation. The 
address of the new TIOA is returned to the application program 
in the location in which the original data area was specified 
(TCTTEDA or TCAMSIOA) . 

The use of the SAVE operand merely stops CICS/VS overwriting a 
data area that you want to retain. It is still necessary to 
store the address of any such area elsewhere, so that it can be 
accessed later, because the location containing the address is 
overwritten. 
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Input Operations with Mapping (TYPE=IN) 



To request BMS services for input operations, a DFHBMS macro instruction 
of the following format is used: 




TYPE= (IN[ ,SAVE )[ , TEXT ]) 

[ ,MAP= {map-name | YES} ]|[ ,MAPADR= {symbolic-address | YES} ] 

[ ,MAPSET={mapset-name|YES} ]|[ ,MSETADR= 

{symbolic-address| YES} ] 

[ , EOC=symbo lie— address] 

[ ,EODS=symbolic-address] 

[ ,ERROR=symbolic-address] 

[ ,INVMPSZ=symbolic-address] 

[ ,MAPFAIL=symbolic— address] 

[ ,NORESP=symbolic— address ] 

[ ,RDATT=symbolic-address] 



TYPE=IN 



specifies an input mapping operation. Input is accepted from 
the terminal through a terminal control READ/WAIT request. The 
input data is then mapped into the TIOA and made available to 
the application program by placing the TIOA address at TCTTEDA. 
The fields entered as part of the input data stream are 
available to the application program under the field names 
specified in the DFHMDF macro instructions by which they are 
defined, suffixed with the letter I to correspond to the name 
generated by CICS/VS in the definition of the area. 

The following types of data are not mapped, but are left in the 
TIOA unaltered. 

• data from TCAM-supported 3600 or 3790 

• data from VTAM-supported 3600 or 3650 (except 3 650 host 
conversation (3270) logical unit) 

• data from 3790 

• word processing data streams, that is, data received from a 
word processing medium type 1, 2, 3 or 4. 

If DFHBMS TYPE=IN macro instructions are used to read data 
from a VTAM batch logical unit, the inbound function 
management headers (FMHs) will be removed before the data 
is placed in the TIOA. If an FMH is required, the 
application programmer should issue a DFHTC TYPE=READ macro 
instruction, deal with the FMH, and then issue a DFHBMS 
TYPE=MAP macro instruction to map the data. Inbound FMHs 
are applicable only to batch logical units. 
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SAVE 

when used with IN, specifies that the data area addressed by 

TCTTEDA is not to be altered; a new TIOA is to be acguired for 

the operation, and its address returned in TCTTEDA. 

The use of the SAVE operand merely stops CICS/VS overwriting a 
data area that you want to retain. It is still necessary to 
store the address of any such area elsewhere, so that it can be 
accessed later, because the location containing the address is 
overwritten. 

TEXT 

indicates that uppercase and lowercase characters are contained 
in the input data stream. 

This parameter is used to override a FEATURE=UCTRAN 
specification in the DFHTCT macro instruction used by the 
system programmer for the input terminal. (See the CICS/VS 
System Programmer's Reference Manual .) 
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Building Output Pages Using Maps (TYPE=PAGEBLD) 

To build an output page cumulatively, using maps, the application 
program uses the DFHBMS TYPE=PAGEBLD macro instruction. This causes the 
data in the area defined by a specified symbolic description map to be 
mapped according to the physical map. The mapped data is positioned 
within an area large enough to contain one page of output. The 
application programmer issues another DFHBMS TYPE=PAGEBLD macro 
instruction to map and position the next portion of the output page. 
The mapping operation continues until the application program has 
completed the message to be sent to the terminal. 

Because of CICS/VS terminal paging facilities, the application 
programmer need not keep track of when a page is full. He can either 
let BMS force a new page automatically or include the OFLOW operand in 
the DFHBMS TYPE=PAGEBLD macro instructions to cause BMS to transfer 
control to an overflow routine (which the programmer must provide) when 
a page of data cannot contain the data to be mapped. 

The format of the DFHBMS TYPE=PAGEBLD macro instruction is as 
follows: 



TYPE=(PAGEBLD[, {OUT[ , WAIT ]| STORE |RETURN} ] 

[ ,SAVE][ , ERASE ][ ,ERASEAUP][ ,LAST ]) 
[ ,DATA={NO|YES|ONLY} ] 
[ ,MAP= {map— name | YES} ] 
[ ,MAPSET={mapset— name |YES} ]| 

[ ,MSETADR = {symbolic-address| YES} ] 
[ ,CTRL= ([ PRINT ][, fL40 I L64 1 L80 I H0NE0M 1 ] 

[ ,FREEKB][ , ALARM ][ ,FRSET]) ] 
[,CURSOR = {number|YES} ] 
[ ,FMHPARM={parameter|YES} ] 
[ ,LDC= {mnemonic | YES} ] 
[ ,PROPT=NLEOM] 
[ ,REQID= {prefix | YES} ] 
[ ,ERROR=symbolic-address] 
[ ,IGREQID=symbolic-address] 
[ ,INVLDC=symbolic— address] 
[ ,INVMPSZ=symbolic-address] 
[ ,INVREQ=symbolic— address) 
[ ,NORESP=symbolic— address ] 
[ ,OFLOW=symbolic-address) 
[ ,RETPAGE=symbolic— address ] 
[ ,TSIOERR=symbolic-address] 

[ ,IGREQCD=symbolic— address] >Asserabler only 

[ ,WRBRK=symbolic-address] >CICS/OS/VS only 




where: 



TYPE=PAGEBLD 



indicates that one page of data is to be accumulated and 
formatted from data submitted through multiple PAGEBLD 
requests. In each PAGEBLD reguest, a map defines the 
number of lines and columns that the data is to occupy on 
the page. When a page is complete, as defined by one or 
more maps, it is written according to an OUT, STORE, or 
RETURN disposition. 
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HAP POSITIONING 



The position of a map on a screen is determined by two major factors: 
the current contents of the screen, and the values coded for the LINE, 
COLUMN, and JUSTIFY operands of the DFHMDI macro. Positioning is also 
affected if the DFHMDI macro specifies HEADER=YES or TRAILER=YES, and by 
the depth of the deepest trailer map in the map set. 



The Screen Contents 



At any instant, the part of the screen which is still available for maps 
is in the form of either an L, a reversed L, a rectangle or an inverted 
T , as shown by the unshaded area in the following diagram. 



next column left reference next column right reference 
from left column from right column 



current line 



next free line 




trailer size 
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The shape and size of this area is represented internally by four 
variables: current line, next free line, next column from left, and 
next column from right. 

Three other pointers are maintained that are relevant to map 
placement though they do not affect the area available: left reference 
column and right reference column, which are used when COL=SAME is 
specified, and trailer size. 



The Trailer Area 

The trailer size is equal to the number of lines that would be occupied 
by the deepest trailer map in the map set currently in use. It is 
determined when the map set is assembled, and is copied from the map set 
whenever one is loaded. 

The area defined by trailer size is not available for mapping unless 
no overflow routine has been specified or the map has TRAILER=TES 
specified in its DFHMDI macro. 



JUSTI FY =FIRST and JUSTIFY=LAST 

If JUSTIFY=FIRST is specified, the map is placed on a new page, so that 
the only maps above it are the header maps used in overflow processing. 
The LINE operand may also be used with JUSTIFY=FIRST to place the map 
below the top of the page. 

If JUSTIFY=LAST is specified, the map is placed as low as possible on 
the page. For a non— trailer map, this is immediately above the trailer 
area; for a trailer map, it is at the bottom of the page. 

A map defined with JUSTIFY=LAST cannot be used in input operations 

unless it was previously put out without PAGEBLD, in which case 

JUSTIFY=LAST is ignored and the map is positioned at the top of the 
page. 



The LINE Operand 

The LINE operand specifies the line of the screen on which the first 
line of the map is to be placed. The initial determination of this line 
is made without regard to the specification of the COLUMN operand or the 
columns available on the screen on that particular line. If it 
transpires that the map will not fit on the chosen line, the first 
subsequent line that will satisfy the column requirements is selected. 

If LINE=SAME or LINE=NEXT is specified, the initial line selected for 
the start of the map is the current line or the next free line , 
respectively. If a number is specified in the LINE operand, the line 
with that number is selected, provided the number is greater than or 
equal to the number of the current line; if not, the overflow condition 
is raised so that the map can be placed on the next page. 

The line selected becomes the new current line and, if it is below 

the next free line, the next free line is reset to the same line; the 

next column from the left and right are also reset, to the left and 
right margins respectively. 
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If the line selected is such that the end of the map extends into the 
trailer area for a non— trailer map or beyond the end of the page for a 
trailer map, the overflow condition is raised and the map will be placed 
on the first available line of the next page when the request is 
reissued after handling the overflow. 



The COLUMN and JUSTIFY Op erand s 

The COLUMN specification may be either NEXT, SAME, or a number and is 
processed in conjunction with the LEFT or RIGHT specification of the 
JUSTIFY operand. JUSTIFY=LEFT is the default and implies that the 
column specification is related to the left-hand margin. Conversely, 
JUSTIFY=RIGHT implies that the column specification is related to the 
right— hand margin. For the purposes of this explanation, it is assumed 
hereafter that JUSTIFY=LEFT has been specified (or applied by default) . 

If COLUMN=NEXT is specified, the column chosen for the map is the 
next column from the left. If a numeric value is specified, the column 
with that number is chosen, counting from the left. If COLUMN=SAME is 
specified, the left reference column is chosen. (The left reference 
column is the one that was most recently specified by number with 
JUSTIFY=LEFT.) 

The map is then checked to ensure that its right margin is not to the 
right of the next column from the right. If it is, the map will not fit 
in the leg of the inverted T, so a new line must be selected. This will 
be either the next full line or, if the map is too deep, the first 
available line on the next page. 

Finally, the column pointers are updated by setting the next column 
from the left to the right margin of the map, and, if COL=number was 
specified, by setting the left reference column to the specified column 
number. 



Pageftuilding Examples 

The effects of the mechanisms described above are illustrated by the 
following examples. The examples show the interactions between SIZE, 
LINE, COLUMN, and JUSTIFY=LEFT or RIGHT; header and trailer maps and 
JUSTIFY=FIRST or LAST are not brought into the examples. 

In processing a PAGEBLD request, BMS determines whether the area of 
the page required by the map is wholly available or whether any part of 
it has been used by an earlier PAGEBLD request. "Used" means actually 
filled by a map or rendered unavailable as described below. 
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1. When the LINE operand of the DFHMDI macro is coded, all lines above 
the specified line are rendered unavailable. 

Example ; A DFHMDI . . . ,LINE=3, . . . 



y///////////////////m\ 



Map A 



2. When JUSTIFY=LEFT is coded (or applied by default), all columns to 
the left of the leftmost map column, for the full depth of the map, 
are rendered unavailable. 

Example ; A DFHMDI . . . ,LINE=3,C0LUMN=5, JUSTIFY=LEFT ,. . . 



w 


'///////////////////A 


m. 


Map A 









3. When JUSTIFY=RIGHT is coded, all columns to the right of the 

rightmost map column, for the full depth of the map, are rendered 
unavailable. 

Example; A DFHMDI . . . ,LINE=3,C0LUMN=35 ,JOSTIFY=BIGHT, 





35 1 


V/////////////////A 


w 




Map A 









284 



CICS/VS APRM (ML) 



When two or more maps are placed so that they share certain lines, 
all columns beneath a map that ends higher are rendered unavailable 
to the depth of the map that ends lowest. Similarly rendered 
unavailable are all columns to the left (if the higher map is left 
justified) or to the right (if the higher map is right justified) 
of the •used 1 area beneath the higher map. 



Example (a) : 



A DFHMDI . ..,LINE=3,C0LUMN=2,JUSTIFY=LEFT, . 
B DFHMDI . .. ,LINE=4,COLUHN=20,JUSTIFY=LEFT, 




Example (b) : 



A DFHMDI ...,LINE=3,C0LUMN=2 / J0STIFY=LEFT / .. 
B DFHMDI . ..,LINE=4,COLUMN=20,JUSTIFY=RIGHT, 




Example (c) ; A DFHMDI 
B DFHMDI 



.,LINE=3,COLtJMN=40,JUSTIFY=RIGHT, 
.,LINE=3,C0LUMN=1,JUSTIFY=LEFT,.. 
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Example s howing the effec t of several different maps on one page : 




If BMS discovers that an area of the page directly specified for a 
map has already been used by a previous map, it raises the overflow 
condition, described below under "PAGEBLD Overflow Processing." 



Handling Returned Pages 



Whenever one or more pages have been completed and the programmer has 
specified TYPE=RETORN, TCAMSRLA contains the address of a list of 
completed pages. Since more than one page of output may result from a 
single BMS output reguest, there may be more than one entry in the list 
for a given terminal type. All entries for a particular terminal type 
immediately follow one another in the list. The list is laid out as 
follows: 

I TC | Page Buffer | TC | Page Buffer | X»FP ... FF» | 

i i 



4 bytes 



4 bytes 



4 bytes 



TC = Terminal code (see "Terminal Code (TC) Table," later in this 
chapter) . 

The page buffer pointer points to an area of USER— class storage which 
has a 12— byte prefix similar to that of a terminal input/output area 
(TIOA), as follows: 



| CICS/VS Storage Acctng | Buffer Length | Reserved | Data 



8 bytes 



2 bytes 



2 bytes 



x bytes 
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At this point, page buffers are on the USER— class storage chain and 
are disassociated from BMS control blocks; it is therefore the user f s 
responsibility to release page buffers when they are no longer needed. 
The storage containing the list of buffers should not be freed by the 
programmer; it is the intention of BMS to reduce processing time by 
reusing the list. This list will be altered by the next BMS request. 
Therefore, the programmer must save the contents before issuing the next 
BMS request. 

Subsequent output of pages should normally be done using BMS. The 
use of the DFHTC macro to handle the output of paqes is not recommended. 
However, if a DFHTC TYPE=WRITE macro is used, st\ .. je must be obtained 
by a DFHSC TYPE=GETMAIN macro with the CLASS=TERM operand included, and 
the output pages moved to the TIOA so acquired. The DFHTC TYPE=WRITE 
macro can then be used to transmit the pages from this new TIOA. 

When terminals of the 3270 Information Display System are used, the 
write control character (WCC) containing the CTRL specification can be 
found at TIOACLCR in the page buffer after addressability to the area 
has been established. (TIOACLCR is a defined field in DFHTIOA and is 
addressable if the buffer address is loaded into TIOABAR.) 



PAGEBLD Overflow Processing 

Overflow occurs when the number of lines in the requested map plus the 
number of lines in the largest trailer map in the map set (if there are 
any trailer maps) is greater than the number of lines remaining in the 
page being built for the terminal involved in an output operation. For 
TCAH and VTAM terminals having LDC support, pages are accumulated 
individually by LDC mnemonic. Therefore, overflow may occur at end of 
page for each different LDC mnemonic used in different BMS requests. 
The LDC mnemonic is passed to the user^s overflow routine in TCAMSLDM, 
and the LDC numeric value is passed in TCAMSLDC. PAGEBLD overflow can 
occur on a logical message being built for a ROUTE environment. If the 
ROUTE environment was created with a route list containing more than one 
LDC mnemonic, then the returned LDC mnemonic and numeric value is the 
first LDC mnemonic resolved in the route list. 

The routine to which control is transferred must be in the 
application program, but no special considerations apply. The data 
which was to have been mapped, but which caused the overflow, is not 
mapped by BMS and remains unaltered in the TIOA. 

If a DFHBMS TYPE=ROUTE macro instruction has not been previously 
issued, there is only one destination. If a DFHBMS TYPE=ROUTE macro 
instruction has been issued, the logical message is probably being built 
for a multiple-destination environment. Since the application 
programmer has the capability of concurrently building pages for 
terminals that have different— sized output, overflow may occur at 
different times for different terminal groups. The overflow routine 
gets control every time any one of the destinations or groups of 
destinations encounters an overflow condition, that is, every time a 
specified map will not fit a page. The application program overflow 
routine must determine which destination or group of destinations has 
encountered the overflow. 

Upon return to the application program from a DFHBMS TYPE=ROUTE macro 
instruction, a count (relative to one) of the number of destinations or 
groups of destinations is available in TCAMSOCN. This overflow control 
count tells the application programmer how many overflow control areas 
(for example, accumulators) he may want to keep. Whenever the overflow 
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routine gets control, TCAMSOCN indicates the relative overflow control 
number of the destination that has encountered the overflow. This 
number indicates which control area should be output, perhaps through 
one or more trailer maps. In addition to the relative control count, 
BMS returns the current page number for the destination that has 
encountered the overflow. This page number is located at TCAHSPGN. 

To place trailer data on a page, the programmer codes DFHBMS 
TYPE=PAGEBLD request (s) to process the trailer data. The map (s) used to 
format the data must contain TRAILER=YES so that the amount of space on 
the page to reserve for overflow can be calculated. More than one 
trailer map may be placed on a page. There should be a dummy trailer 
map (not otherwise used) in the map set specifying the number of lines 
to be reserved for trailer data if no single trailer map extends over 
the total number of lines required for trailer data (see Figure 4.3—1) . 
Maps used to map trailer data may contain JUSTIFY=LAST to force their 
placement at the bottom of the page. If the programmer tries to place 
more lines of trailer data on the page than are available, that trailer 
data is placed on a separate page by itself. Still another page is 
built to continue mapping with or without a header map. 




No dummy trailer required. 



TR1 



TR2 



TR3 



Dummy trailer required. 



Figure 4.3—1. Use of Trailer Maps in PAGEBLD Mapping Operations 

To place header data on a page, the programmer codes DFHBMS 
TYPE=PAGEBLD request (s) to process the header data. The map (s) used to 
map header data must specify JUSTIFY=FIRST to complete processing of the 
previous page if that has not been done, and to begin a new page. 
(JUSTIFY=FIRST is ignored if BMS is positioned at the top of a new 
page.) If the programmer tries to place more header data on the page 
than the page can contain, multiple pages are created. 

I After overflow has been raised, the first map to be used in a 

| TYPE=PAGEBLD request must be one that specified JOSTIFY=FIRST. Failure 

| to do this will result in overflow being raised again immediately. 

When all trailer and/or header data has been processed, the 
programmer must reissue the DFHBMS request that caused the overflow, 
since this data has not yet been mapped for all destinations. 

If the user does not specify an overflow routine while issuing 
PAGEBLD requests, no overflow occurs and new pages will be forced 
automatically. If a header is to be placed on the first page and a 
trailer on the last, the OFLOW parameter would not be used. 
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A general overview of overflow processing is given in the flowchart 
in Figure 4.3—2. 




Application program prepares & issues a 
PAGEBLD request and includes an 
OFLOW routine address 



DFHBMS macro expansion BALRs to 
BMS program 



BMS programs process the request 



DFHBMS macro expansion 
checks to see if an 
overflow occurred 



DFHBMS macro expansion has returned 
control to application program and the 
PAGEBLD request has been mapped for 
all of the destinations. 



The application program updates all 
overflow control areas to reflect the last 
PAGEBLD request (which may or may 
not have caused an overflow). 




APPLICATION PROGRAM'S 
OVERFLOW ROUTINE 

1 ) Save sufficient information to be able 
to reissue the request that just caused 
an overflow. 

2) Using the overflow control number in 
TCAMSOCN, determine the appropriate 
control area to map its contents via 
PAGEBLD requests, specifying trailer 
map(s). 

3) The current page number is available at 
TCAMSPGN and could be supplied with 
the data to be mapped by the trailer 
map(s); and/or this page number could 
be incremented and supplied with the 
data to be mapped by header map(s). 

4) At this point, do not update any control 
areas to reflect the original PAGEBLD 
request that caused the overflow. 

5) Do reinitialize the control areas that just 
supplied the data for overflow pro- 
cessing. 

6) Do return to the logic((A))that issued 
the original PAGEBLD request and 
reissue that request. 




Figure 4.3—2. Overflow Processing by Application Programs under BMS 
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Building Output Pages without Using Maps (TYPE=TEXTBLD) 

To request the building of pages of data without the use of maps, the 
application program issues DFHBMS TYPE=TEXTBLD macro instructions. 
These macro instructions cause BMS terminal paging to create pages 
containing application— program— supplied text data. The length of the 
data each macro instruction is to process must be supplied in TIOATDL, 
prior to issuing the macro instruction. Completion of a logical message 
is signaled by a DFHBMS TYPE=PAGEOUT macro instruction. The beginning 
and ending of pages are handled by BMS and need be of no concern to the 
application program. 

The format of the DFHBMS TYPE=TEXTBLD macro instruction is as 
follows: 




TIPE=(TEXTBLD[ , {00T[ , WAIT ] | STORE |RETURN} ] 

[ ,SAVE][ ,ERASE][ ,LAST ]) 
[ ,HEADER= {symbolic— address | YES} ] 
[ ,JUSTIFY= {FIRST |LAST | line-number | YES} ] 
[ ,TRAILER= {symbolic— address | YES} ] 
[ ,CTRL= ([ PRINT ][ , {L40 | L64 | L80 | H0NB0M1 ] 

[,FREEKB][ , ALARM]) ] 
[ ,C0RSOR= {number | YES} ] 
[ ,FMRPARM= {parameter | YES} ] 
[ ,LDC={mnemonic| YES} ] 
[ ,PROPT=NLEOM] 
[ ,REQID= {prefix | YES} ] 
[ ,ERROR=symbolic-address] 
[ ,IGREQID=symbolic— address] 
[ ,INVLDC=symbolic— address ] 
[ ,INVREQ=symbolic— address ] 
[ ,NORESP=symbolic-address] 
[ ,RETPAGE=symbolic— address ] 
[ ,TSIOERR=symbolic— address] 
[ ,IGREQCD=symbolic— address] — 
[ r WRBRK=symbolic-address ] 



>Assembler only 
>CICS/OS/VS-2741 only 



where: 



TYPE=TEXTBLD 



indicates that (1) one page of output is to be formed from 
data submitted through multiple TEXTBLD requests, or (2) 
multiple pages of output are to be formed from one TEXTBLD 
request. When TEXTBLD is specified, no map is used. When 
no more data can fit on a page, the page is written 
according to the OUT, STORE, or RETURN disposition (see 
below), and another page is started if necessary. 
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Direct Output (TYPE=OUT) 



An output request in which neither TEXTBLD nor PAGEBLD is specified can 
be issued by the application program. Such a request may cause multiple 
pages to be written as output, but multiple requests cannot be issued to 
accumulate and format data within one page. One map may be used to 
format data on one page, and that page may be written directly to the 
terminal (TYPE=O0T) . The rules governing this type of output are as 
follows: 

• Multiple requests cannot be accumulated to build one page, whether 
mapped or unmapped. 

• When using maps, one request cannot build more than one page. 

• When not using maps, a single reguest can result in more than one 
page. 

• If the disposition is STORE, multiple requests can cause multiple 
pages (each reguest starting a new page) to be included in one 
logical message . 

• For both mapping and nonmapped operations, if the disposition is 
STORE, a DFHBMS TYPE=PAGEOUT request must be issued to terminate 
the logical message. 



TYPE=([ {OUT[ ,WAIT]|STORE|RETURN} ][ ,NOEDIT][ ,SAVE ] 

[ , ERASE ][ ,ERASEAUP][,LAST]) 
[ , DATA= {NO | YES | ONLY} ] 

[ ,MAP= {map-name | YES} ]| ,MAPADR= {symbolic-address | YES} ] 
[ ,MAPSET={mapset-name| YES} ]|[ ,MSETADR= 
{symbolic— address | YES} ] 
[ ,CTRL=([ PRINT ][ ,{L40|L64|L80|HONEOM} ] 

[ ,FREBKB][, ALARM ][,FRSET]) ] 
[ ,CURSOR= {number | YES} ] 
[ ,FMHPARM= {parameter | YES} ] 
[ , LDC= {m nemonic | YES} ] 
[ ,PROPT=NLEOM] 
[ ,REQID={prefix| YES} ] 
[ ,ERROR=symbolic-address ] 
[ ,IGREQID=symbolic— address] 
[ ,INVLDC=symbolic-address] 
[ ,INVMPSZ=symbolic-address] 
[ ,INVREQ=symbolic-address] 
[ ,NORESP=symbolic-address] 
[ ,RETPAGE=symbolic— address] 
[ ,TSIOERR=symbolic— address ] 

[ ,IGREQCD=symbolic-address] >Assembler only 

[ ,WRBRK=symbolic-address] >CICS/OS/VS only 




where: 
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TYPE=OOT 

indicates that the output is to be written to the 
originating terminal at once if that terminal is to receive 
it. 

Once a DFHBMS macro with OUT disposition has been issued, 
the application program must not issue a DFHSC 
TYPE=FREEMAIN,RELEASE=ALL macro until either a DFHBMS 
TYPE=PAGEOUT or DFHBMS TYPE=PORGE macro has been issued. 
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Terminating a Logical Message (TYPE=PAGEOUT) 



When the combining of pieces of data to form a logical message has been 
requested by means of DFHBMS TYPE=PAGEBLD or TYPE=TEXTBLD macro 
instruction (s) , such combining must be terminated by means of a DFHBMS 
TYPE=PAGEOUT macro instruction. A logical message created by means of 
one or more noncumulative output requests with STORE disposition must be 
terminated by a DFHBMS TYPE=PAGEOUT macro instruction. The format of 
this macro instruction is as follows: 




TYPE= (PAGEOUT[ ,LAST ]) 

[,CTRL=([ {PAGE | AUTOPAGE} ], {BETA IN | RELEASE} ]) 

[ ,EODPURG= {AUTOJOPER} ] 

[,FMHPARM= {parameter | YES} ] 

[ / TRAILER= {symbolic-address | YES} ] 

[ ,TRANSID=transaction code] 

[ , WRBRK= {symbolic-address | CURRENT | ALL} ] 

[ , ERROR=symbolic-address ] 

[ , NORESP=symbolic-address ] 

[ , RETPAGE=symbolic-address ] 

[ ,IGREQCD=symbolic— address ] 

[ ,TSIOERR=symbolic-address] 



>Assembler only 



where: 



TYPE=PfcGEOUT 



specifies the termination of a logical message. No data is 
formatted in response to this request. Any remaining data 
in the page buffer is processed according to the OUT, 
STORE, or RETURN described in the previous macro 
instruction. If a logical message is being built for a 
routing environment, PAGEOUT completes the logical message 
under route . An additional PAGEOUT macro instruction is 
required to complete a logical message to the originating 
terminal. 

If an error occurs during PAGEOUT processing, control is 
returned to the application program, and the RETAIN or 
RELEASE specifications are ignored. The logical message is 
not considered complete. The application program should 
either retry the PAGEOUT operation or PURGE the message. 

Any logical message that has been started but not completed 
when a DFHSP (sync point) macro is issued is forced to 
completion by an implied TYPE=PAGEOUT macro. 
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Deleting a Logical Message (TYPE=PURGE) 

To discontinue the process of building a logical message, a DFHBMS 
TYPE=PURGE macro instruction is issued. This instruction causes the 
portions of the message already built in main storage or on temporary 
storage to be deleted and returns control to the application program at 
the instruction following the DFHBMS TIPE=PURGE macro expansion. (The 
TYPE=PORGE instruction is not to be used if TYPE=RETORN was used in the 
BMS PAGEBLD or TEXTBLD request.) The format of the macro instruction is 
as follows: 



1 - 
1 


1 
1 




i 
■ 


1 

1 

1 


DFHBMS | 
i 


TYPE=PURGE 


1 
1 


1 
1 


1 

1 L 




1 
■ 



where: 

TYPE=PURGE 

specifies that all data prepared for a logical message but not 
yet transmitted to a terminal is to be deleted from the system. 
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Message Routing (TYPE=ROUTE) 

A DFHBMS TYPE=ROUTE request defines the terminal and/or operator to 
receive the message created by subsequent DFHBMS output requests. The 
message may be directed to any or all BMS— supported terminals. The 
ROUTE macro defines the destination of the message; it does not cause 
transmission to occur. The ROUTE macro must thus be followed by one or 
more BMS ouput macros. A DFHBMS TYPE=PAGEOUT request causes the logical 
message to be completed and terminates the effect of the DFHBMS 
TYPE=ROUTE macro instruction. 

If a ROUTE request followed by one or more BMS output requests is not 
terminated by a PAGEOUT request before a subsequent ROUTE request is 
issued or before the application program terminates, the message is 
forced to completion. Since the application program did not issue the 
PAGEOUT reguest, BMS applies the PAGEOUT defaults to the message. A 
ROUTE request may be issued immediately following another ROUTE request. 
In this case, the first ROUTE request is nullified, and the second one 
determines the routing environment. 

A message is considered undeliverable to a destination if it cannot 
be delivered within a certain interval after the reguested delivery 
time. This interval is specified in the PRGDLAI operand of the DFHSG 
PROGRAM=BMS macro instruction by the system programmer. If the PRGDLAY 
operand is not included, no action is taken for undelivered messages and 
the message awaits delivery indefinitely. If PRGDLAY is specified, the 
transient data destination CSMT is notified of the number of 
undeliverable messages purged for a destination; the application 
programmer can ensure that additional documentation is provided for an 
undeliverable message by including the ERR TERM operand in the DFHBMS 
TYPE=ROUTE macro instruction. Examples of situations causing 
undeliverable messages might occur, for example, when a message is 
routed to a terminal that is out of service, or when an operator 
identification is specified with a terminal identification and that 
operator is not signed on that terminal at the time the message is to be 
delivered. 

If operating in a DL/I environment, a message should not be routed to 
more than 40 terminals by using only one TYPE=ROUTE macro. If it is 
required to route to more than 40 terminals, several TYPE=ROUTE macros 
must be issued, each with a LIST operand that specifies a list of 
terminals with more than 40 entries. Each TYPE=ROUTE macro must be 
issued with all other DFHBMS macros relevant to the message. 

The format of the DFHBMS TYPE=ROUTE macro instruction is as follows: 
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DFHBMS 



TYPE=ROUTE 

[ ,ERRTERM={termid|ORIG|YES} ] 

[ ,LIST= {symbolic address | YES | ALL} ] 

[ ,OPCLASS= {decimal-value,... |YES} ] 

[ ,TITLE= {symbolic— address | YES} ] 

[ ,INTRVAL= {numeric-value | YES} ]|[ ,TIME = 

{numeric— value | YES} ] 

[ ,LDC={mnemonic|YES} ] 

[ ,PROPT=NLEOM ] 

[ ,REQID= {prefix | YES} ] 

[ ,ERROR=symbolic-address] 

[ ,IGREQID=symbolic— address] 

[ ,INVET=symbolic-address] 

[ ,NORESP=symbolic— address ] 

[ ,RTEFAIL=symbolic— address] 

[ ,RTESOME=symbolic— address ] 



where: 

TYPE=ROOTE 

specifies the initiation of an output page routing operation. 



Dis p o sition and Message Routiner 



A routed logical message can be built using either of two dispositions: 
STORE or RETURN. The first BMS output request issued following the 
ROUTE request (with some exceptions noted below) determines the 
disposition of the logical message. This first request may specify 
STORE or RETURN; if neither is specified, the default is STORE. Once 
established, the disposition remains unchanged until the logical message 
is completed (PAGEOUT) . It need not be repeated for subsequent 
requests. An output request specifying a disposition that is not in 
effect results in a return code of INVREQ. 

A disposition of STORE is the normal disposition and finally results 
in the message either being delivered or deleted. A disposition of 
RETURN causes the routed logical message to be returned to the 
application program. It is the responsibility of the application 
program to deliver the logical message. 

A task can converse with the terminal to which it is currently 
attached (assuming the task is terminal— oriented) during the time that 
it is building the logical message. That attached terminal is known as 
the direct terminal : a terminal to which the message is to be routed is 
known as a routing terminal . If any input requests (DFHBMS TYPE=IN or 
TYPE=MAP) are encountered while the message is being built, they are 
processed as usual. To transmit output to the direct terminal while the 
routed logical message is being built, the task can issue non— TEXTBLD, 
non— PAGEBLD requests with an explicit disposition of OUT. The 
disposition of OUT isolates the output request to the direct terminal 
from the requests that are building the routed logical message . 

The following points summarize rules for conversation with the direct 
terminal while a routed logical message is being built: 

• OUT must be specified in any output request that is to go to the 
direct terminal. 
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TEXTBLD and PAGEBLD requests with a disposition of OUT are invalid 
and result in a return code of INVREQ. 

The direct terminal may be included in the routing environment 
without impairing the ability to converse with it while under 
ROUTE. Data routed to the direct terminal will be delivered as 
though the ROUTE had been issued from another terminal. 



A list of "abridged" requests, in order of execution, is given below. 
The action taken by BMS for each is indicated. 



Req uest 
DPHBMS TYPE=OUT 
DFHBMS TYPE=ROUTE 
DPHBMS TYPE=OUT 
DFHBMS TYPE=IN 
DFHBMS TYPE=TEXTBLD 

DFHBMS TYPE=OUT 

DFHBMS TYPE=TEXTBLD, RETURN 

DFHBMS TYPE=TEXTBLD 
DFHBMS TYPE=PAGEBLD, STORE 

DFHBMS TYPE=PAGEBLD,OUT 

DFHBMS TYPE=TEXTBLD, STORE 
DFHBMS TYPE=PAGEOUT 

DFHBMS TYPE=OUT 



Act ion Taken by B MS 

Transmit to direct terminal. 

Establish routing environment. 

Transmit to direct terminal. 

Receive from direct terminal. 

First output request eligible for routing 
establishes default disposition of STORE 
and TEXTBLD as mode of page building. 

Transmit to direct terminal. 

INVREQ — routed logical message has 
already established a disposition of STORE 

Continue building routed logical message. 

INVREQ — routed logical message being 
built with TEXTBLD requests cannot 
tolerate PAGEBLD request. 

INVREQ - cannot issue PAGEBLD or TEXTBLD 
request to direct terminal while building 
a routed logical message. 

Continue building routed logical message. 

Terminate routed logical message and 
routing operation. 

Transmit to direct terminal. 



Status Flag Byte in User— Supplied Route List 



Each route list entry contains a status flag byte used by BMS to 
indicate to the application program the status of the destination at the 
time the DFHBMS TYPE=ROUTE macro instruction was issued. Upon return, 
the application program can investigate the status byte for each route 
list entry and take appropriate action. 

The status flag byte settings are shown in Figure 4.3—3. Their 
meanings are explained in greater detail in the text that follows. 
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- i 

Status Flaq 1 


Condition 


Assembler 


COBOL 


PL/I | 


(See explanation below.) 








ENTRY SKIPPED 


X»80» 


12-0-1-8 


10000000 | 


INVALID TERMINAL 


X«40« 


no punches 


01000000 | 


IDENTIFICATION 








TERMINAL NOT SUPPORTED 


X«20» 


11-0-1-8-9 


00100000 | 


UNDER BMS 








OPERATOR NOT 


X«10« 


12-11-1-8-9 


00010000 | 


SIGNED ON 








OPERATOR SIGNED ON 


X«08» 


12-8-9 


00001000 | 


UNSUPPORTED TERMINAL 








INVALID LDC MNEMONIC 


X«04» 


12-4-9 


00000100 | 



Figure 4.3-3. BMS Status Flags 



ENTRY SKIPPED 

A route list entry that is flagged as skipped was not included 
in the resolved routing environment. If an entry has been 
skipped, another flag indicating why the entry was skipped may 
be on in the status byte. This second flag could be one of the 
following : 

• INVALID TERMINAL IDENTIFICATION 

• TERMINAL NOT SUPPORTED UNDER BMS 

• OPERATOR NOT SIGNED ON - only an operator identification 
was specified in the route list entry and that operator was 
not signed on any terminal 

• OPERATOR SIGNED ON UNSUPPORTED TERMINAL 

• INVALID LDC MNEMONIC 

!f only the ENTRY SKIPPED flag is on, neither a terminal 
identification nor an operator identification was specified in 
the route list entry. 

INVALID TERMINAL IDENTIFICATION 

This flag indicates that the terminal identification specified 
in the route list entry does not have a corresponding TCTTE in 
the terminal control table. This entry is also flagged as 
ENTRY SKIPPED. 

TERMINAL NOT SUPPORTED UNDER BMS 

This flag indicates that the terminal identification specified 
in the route list entry is for a terminal type that is not 
supported under BMS or the terminal table entry indicated that 
the terminal identification was not eligible for routing. This 
entry is also flagged as ENTRY SKIPPED. 
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OPERATOR NOT SIGNED ON 

This flag indicates that the specified operator is not signed 
on. Any one of the following conditions causes this flag to be 
set: 

1. An operator identification was specified with a terminal 
identification, but the specified operator was not signed 
on the terminal. This entry is not skipped. 

2. An operator identification was specified without a terminal 
identification, and the operator was not signed on any 
terminal. This entry is also flagged as ENTRY SKIPPED. 

3. The OPCLASS operand was specified with the DFHBMS 
TYPE=ROUTE macro instruction and a terminal identification 
was specified in the route list entry, but the operator 
signed on the terminal did not gualify under OPCLASS. This 
entry is not skipped. 

OPERATOR SIGNED ON UNSUPPORTED TERMINAL 

This flag indicates that only an operator identification was 
specified in the route list entry, and that operator was signed 
on a terminal not supported by BMS. This entry is also flagged 
as ENTRY SKIPPED. The unsupported terminal identification is 
returned in that route list entry at URLTRMID for informational 
purposes only. 

INVALID LDC MNEMONIC 

This flag indicates that one of the following conditions 
occurred: 

1. The LDC mnemonic specified in the route list does not 
appear in the LDC list associated with the TCTTE. 

2. The device type generated in the system LDC table for the 
specified or implied LDC mnemonic is not the same as the 
device type for the first LDC specified in the route 
environment. 

A symbolic storage definition of the user— supplied route list 
is available on the source library (s) under the member name 
DFHURLDS. This symbolic storage definition can be used as an 
aid in building the route list, and if necessary, in testing 
the status flag byte for each entry upon return from a DFHBMS 
TYPE=ROUTE request that refers to a list. The symbolic base 
register is URLBAR. 
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Checking the Response to a BMS Request (TYPE=CHECK) 

The format of the DFHBMS TYPE=CHECK macro instruction is as follows: 




TYPE=CHECK 

[ ,EOC=symbolic— address] 
[ ,EODS=symbolic-address ] 
[ ,ERROR=symbolic-address] 
[ ,IGREQID=symbolic— address ] 
[ ,INVET=symbolic-address] 
[ , I NVLDC=symbolic— address] 
[ , IN VMPSZ=symbolic— address ] 
[ , INVREQ=symbolic-address] 
[ ,MAPFAIL=symbolic— address ] 
[ , NO RESP=symbolic— address] 
[ ,RETPAGE=symbo lie— address ] 
[ ,RTEFAlL=symbolic-address ] 
[ ,RTESOME=symbolic— address] 
[ ,IGREQCD=symbolic— address ] 
[ ,TSIOERR=symbolic— address ] 



->Assembler only 



where: 

TYPE=CHECK 

indicates that the BMS response to a request for BMS services 
is to be checked. 

Some response codes may appear in combination with other response 
codes. These combinations are: RTEFAIL and INVET, and RTESOME and 
INVET. The order used by BMS in checking for all conditions that the 
application programmer specifies is as follows: NORESP, TSIOERR, 
INVREQ, RETPAGE, MAPFAIL, RTEFAIL, RTESOME, INVET, IGREQID, INVLDC, 
INVMPSZ, EODS, EOC, and ERROR. Thus, if the application programmer has 
specified INVET and RTEFAIL and both of these responses apply, BMS 
transfers control to the user— written exception— handling routine 
identified in the RTEFAIL operand. In this situation, the INVET operand 
is not acted upon. 



BMS Response Codes 



To test a BMS response code the application programmer must know the 
codes and their meanings. For this approach, the application programmer 
can access the response code (s) at TCAMSRC1, TCAMSRC2, and TCAMSRC3. 
The possible response codes and the conditions to which they correspond 
are identified in the right— hand columns of Figure 4.3-4. DFHBMS 
service requests for which the conditions are applicable are shown at 
the left. The keywords are explained in detail at the end of this 
chapter (see "Operands of DFHBMS Macros") . 
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DFHBMS | 




Response Code 




Response | 


Service 
Request 


Condition 








Code | 
Location | 


Assembler 


COBOL 


PL/I 


INPUT, OUTPUT, 


NORESP 


X»00» 


LOW-VALUES 


00000000 


TCAMSRC1, | 


ROUTING, CHECK 


(Normal 
response) 








TCAMSRC2,and| 
TCAMSRC3 | 


OUTPUT, CHECK 


INVREQ 
(Invalid 
request) 


X«01* 


12-1-9 


00000001 


TCAMSRC1 | 


OUTPUT, CHECK 


RETPAGE 
(Return Page) 


X»02« 


12-2-9 


00000010 


TCAMSRC1 | 


INPUT, CHECK 


MAPFAIL 

(Mapping at- 
tempt failure) 


X»04» 


12-4-9 


00000100 


TCAMSRC1 | 


INPUT, CHECK 


EODS 
(End of data 
set) 


X»04« 


1 2-4-9 


00000100 


TCAMSRC3 | 


INPUT, OUTPUT, 


INVMPSZ 


X»08» 


12-8-9 


00001000 


TCAMSRC1 | 


CHECK 


(Invalid map 
size) 










INPUT, CHECK 


EOC 
(End of 
chain) 


X»08» 


12-8-9 


00001000 


TCAMSRC3 | 


OUTPUT, CHECK 


INVLDC 
(Invalid LDC 
mnemonic) 


X'10' 


12-11-1-8-9 


00010000 


TCAMSRC2 | 


OUTPUT, 


IGREQID 


X»10» 


12-11-1-8-9 


00010000 


TCAMSRC3 | 


ROUTING, CHECK 


(Ignore REQID 
specification) 










ROUTING, CHECK 


INVET 
(Invalid er- 
ror terminal) 


X«20» 


11-0-1-8-9 


00100000 


TCAMSRC1 | 


ROUTING, CHECK 


RTESOHE 
(Routing to 
only some 
terminals) 


X«40« 


no punches 


01000000 


TCAMSRC1 | 


ROUTING, CHECK 


RTEFAIL 
(Routing 
failure) 


X«80» 


12-0-1-8 


10000000 


TCAMSRC1 | 


INPUT, OUTPUT 


ERROR 


See note 


See note 


See note 


TCAMSRC1, | 


ROUTING, CHECK 


(Any response 
other than 
NORESP) 








TCAMSRC2,and| 
TCAMSRC3 | 


OUTPUT, CHECK 


TSIOERR 
(Temporary 
storage I/O 
error) 


X»80» 


12-0-1-8 


10000000 


TCAMSRC2 | 


OUTPUT, CHECK 


IGREQCD 
(Request 
change 
direction 
ignored) 


X»40» 


No punches 


01000000 


TCAMSRC2 | 


Note; The t€ 


ist for the ERRC 
lat is, not X , 0( 


)R response 
) • , not L01 


5 is satisfie 
f-VALUES, or 


jd by a nj 


>t equal | 


condition; t\ 


not 0000C 


)000 for | 


Assembler, CC 


)BOL, and PL/I, 


respective 


sly. 







Figure 4.3—4. BUS Response Codes 
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The following examples show how to examine the response code provided 
by BMS at TCAMSRC1,TCAMSRC2, and TCAMSRC3, and transfer control to the 
appropriate user-written routine accordingly. 



For Assembler Languag e ; 





DPHBMS 


TYPE=(TEXTBLD, 




CLI 


TCAMSRC1,X»00« 




BNE 


ERROR 




CLI 


TCAMSRC2,X , 00 t 




BNE 


ERROR 




CLI 


TCAMSRCS^OO 1 




BE 


GOOD 


ERROR 


DS 


OH 




DFHPC 


TYPE=ABEND 


GOOD 


DS 


OH 



BUILD OUTPUT 

ANY UNUSUAL CONDITIONS, TEST 1 

..YES, GO TERMINATE THE TASK 

..NO, ANY UNUSUAL CONDITIONS, TEST 

..YES, GO TERMINATE THE TASK 

..NO, ANY UNUSUAL CONDITIONS, TEST 

..NO, GO CONTINUE PROCESSING 

YES, TERMINATE THE TASK 

TERMINATE THE TASK 



For COBOL; 



DFHBMS TYPE=(TEXTBLD, STORE) BUILD OUTPUT 
IF TCAMSRC1 NOT = • • THEN GO TO ERROR. 
IF TCAMSRC2 NOT = • • THEN GO TO ERROR. 
IF TCAMSRC3 = • • THEN GO TO GOOD. 



ERROR 



GOOD. 



DFHPC TYPE=ABEND 



TERMINATE THE TASK 



where the value specified within the single quotation marks is an 
unprintable multipunch code for the required hexadecimal value. 



For PL/I ; 



DFHBMS TYPE= (TEXTBLD, STORE) BUILD OUTPUT 

IF TCAMSRC1 = »0»B S TCAMSRC2 = »0»B 

5 TCAMSRC3 = «0»B THEN GO TO GOOD; 
ERROR: 

DFHPC TYPE=ABEND TERMINATE THE TASK 



GOOD: 
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BMS Message Recovery 

BMS provides message recovery for routed and non— routed messages. To be 
recoverable, messages must satisfy the following requirements: 

• The DFHBMS TYPE=STORE operand must have been specified on the BMS 
output requests that built the logical message. 

• The BMS default EEQID (**) or the specified REQID for the logical 
message must have been identified to Temporary Storage Program (via 
the TST) as recoverable. 

• The task that built the message must have reached its logical end 
of task . 

• The Temporary Storage Program (TSP) and the Interval Control 
Program (ICP) must also support recovery. 



Terminal Code (TC) Table 

A terminal code table is established within BMS for reference in 
servicing BMS— supported terminals. There is one entry in this table for 
each terminal supported under BMS. The terminal codes that appear in 
the table are given in Figure 4.3—5. This code appears in the list of 
completed pages available at TCAMSRLA when the application programmer 
has specified that pages of output be returned (that is, RETURN is the 
disposition parameter in the output request) . The code is available at 
TCAMSRI1 when an invalid map size (INVMPSZ) response is returned. 

Code Terminal 

Character Type 

A CRLP or TRMTYPE=TCAM terminals 

B Magnetic Tape 

C Sequential Disk 

D TWX Model 33/3 5 

E 1050 

F 2740 Models 1 and 2 (Without Buffer Receive) 

G 2741 

H 2740 Model 2 (With Buffer Receive) 

I 2770 

J 2780 

K 3780 

L 3270 models with 40— column displays 

M 3270 models with 8 0-column displays 

P Interactive LU (3767, 3770 Interactive); 

3790 Full Function LU; and SCS Printer LUs 

(3270 and 3790) 

Q 2980 Models 1 and 2 

R 2980 Model 4 

U 3601 

V Host Conversational (3653) 
W 3650 User Program 

X 3650/3270 Host Conversational (3270) 

Y Batch LU (3770 Batch) , Batch Data 
Interchange LU (3770, 3790, LUTYPE4) 

Figure 4.3—5. BMS Terminal Code Table 
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Standard Attribute List and Printer Control Characters (DFHBMSCA) 



The application programmer can obtain a set of commonly used 3270 field 
attributes and printer control characters by copying DFHBMSCA into his 
program. For COBOL, this definition must be copied into the Working 
Storage Section. DFHBMSCA consists of a set of EQU statements in the 
case of Assembler language, a set of 01 statements in the case of COBOL, 
and DECLARE statements defining elementary character variables in the 
case of PL/I. One possible use for DFHBMSCA is for the purpose of 
temporarily changing attribute characters in a map. 

The field attributes/printer control characters and corresponding 
symbolic names are listed in Figure 4.3—6. These attributes cannot be 
combined by the application programmer in any manner. If any 
combinations other than those listed are required, the application 
programmer must either use the ATTRB operand of the DFHMDF macro 
instruction to obtain the desired combinations or generate new attribute 
combinations offline. 

Symbolic Field Attribute/ 

Name Prin ter Control Ch aracte r 

DFHBMPEM 3270 Printer end of message 

DFHBMPNL 3270 Printer new-line character 

DFHBMASK Autoskip 

DFHBMUNP Unprotected 

DFHBMUNN Unprotected and numeric 

DFHBMPRO Protected 

DFHBMBRY High intensity 

DFHBMDAR Dark, nonprint 

DFHBMFSE MDT on 

DFHBMPRF Protected and MDT on 

DFHBMASF Autoskip and MDT on 

DFHBMASB Autoskip and high intensity 

Figure 4.3—6. 3270 Field Attributes and Printer Control Characters 



Standard Attention Identifier List (DFHAID) 

To test the method of initiating an incoming READ from the 3270 
Information Display System, the application programmer is provided with 
a set of 3270 attention identifiers (single— character variables called 
AIDs) that can be used to test the value at TCTTEAID. He can obtain 
this set of attention identifiers by copying DFHAID into his program. 
For COBOL, this definition must be copied into the Working Storage 
Section. 

DFHAID consists of a set of EQU statements in the case of Assembler 
language, a set of 01 statements in the case of COBOL, and DECLARE 
statements defining elementary character variables in the case of PL/I. 
The symbolic names for the attention identifiers and the corresponding 
3270 functions are given in Figure 4.3—7. 
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Symbolic Name 3270 Function 

DFHENTER Enter key 

DFHCLEAR Clear key 

DFHOPID Operator Identification Card Reader 

DFHPEN Immediately detectable field 

DFHPA1 PA1 key 

DFHPA2 PA2 key 

DFHPA3 PA3 key 

DFHPF1 PF1 key 



DFHPF24 PF24 key 

Figure 4.3— 7. 3270 Attention Identifiers and Functions 

Programming Considerations for Paging Commands on Display Devices 



The commands used by terminal operators to communicate with CICS/VS BBS 
are collectively known as terminal paging commands, or simply as paging 
commands. They are defined by the system programmer through the DFHSIT 
macro, which is described in the CICS/VS System Progra m mer's R eference 
Manual . Their format and use are discussed in detail in the CICS/VS 
Operator's Gu ide . 

The application programmer must be aware of the terminal paging 
commands in order to write applications that involve terminal operators. 
The use of BMS at map definition time and in executable programs can 
have a significant effect on terminal operator procedures. 

| It is important to note that when in a page retrieval session, that 

| is, when using paging commands, all PA and PF keys are treated as paging 

| commands, regardless of whether or not they have been defined in the 

| SKRXXXX operand of the DFHSIT macro. 

Cursor placement is an important consideration in programming for 
paging commands. Any of the following items can cause a paging command 
not to be the first data read by CICS/VS and therefore not to be 
interpreted as a paging command. 

• After a print operation on a 3270 display, the cursor is set to 
position zero. A paging command entered at this location is not 
recognized unless the last position of the buffer contains an 
attribute byte or the buffer has been cleared. 

• A field sent with DATA=OHLY and no attribute byte in the TIOA is 
written into the buffer without an attribute byte. If the 
application programmer places the cursor in this field and the 
operator keys a paging command beginning at the cursor location, 
the paging command is not recognized. 

Since the field has no attribute byte, the hardware considers the 
data to be an extension of the previously defined field. When the 
operator keys into the middle of the hardware— recognized field and 
presses the enter key, the field is transmitted from the beginning 
of the previously defined field. The data at the beginning of the 
field is examined for a paging command and responded to 
accordingly. 
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Cursor specification in the DFHBMS macro instruction can adversely 
affect operator action if the cursor is not set at the beginning of 
a field. Paging commands entered at a cursor location that is not 
the beginning of a field are not recognized by BMS because data 
transmission starts at the beginning of the field if the field is 
not set to nulls X»00». 
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Operands of DFHBMS Macros 

CTRL = 

PAGEBLD, TEXTBLD, and OUT Macro s 

In DFHBMS TYPE=PAGEBLD, TEXTBLD, and OUT macros, CTRL= is used 
to specify device characteristics related to terminals of the 
3270 Information Display System (including VTAM 3270 logical 
units, 3650 host—conversational (3270) logical units, and 3790 
(3270-display and 3270-printer) logical units) . CTRL=ALARM is 
also valid for TCAM SDLC and VTAM-supported terminals (except 
interactive and batch logical units) , for which all other 
parameters for CTRL are ignored. To be effective, this operand 
must be specified in the DFHBMS TTPE=PAGEBLD macro that causes 
a page of output to be completed, or in the DFHMDI macro for 
the associated map, or in the DFHMSD macro for the associated 
mapset. If the operand is specified in more than one of these 
macros, the specification in a DFHBMS macro will override that 
in a DFHMDI macro, which in turn overrides that in a DFHMSD 
macro. If CTRL is not specified in a request for a 3270, an 
appropriate WCC for the 3270 should be placed in TIOACLCR 
before the request is issued. If this is not provided, the 
default WCC will be used. 

PRINT 

must be specified if the printer is to be started; if 
omitted, the data is sent to the printer buffer but is not 
printed. This operand is ignored for 3270 displays without 
printer features. 

L40,L64,L80,HONEOM 

are mutually exclusive options that control the line length 
on the printer. L40, L64, and L80 force a carrier 
return/line feed after 40, 64, or 80 characters, 
respectively. HONEOM causes the default printer line 
length to be used. 

FREEKB 

specifies that the keyboard should be unlocked after this 
map is written out . If omitted, the keyboard remains 
locked; further data entry from the keyboard is inhibited 
until this status is changed. 

ALARM 

activates the 3270 audible alarm feature. For TCAM and 
VTAM terminals supporting function management headers 
(FMHs) (except interactive and batch logical units) , ALARM 
signals BMS to set the alarm flag in the FMH . 
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FRSET 

is valid only when mapping is used. FRSET indicates that 
the modified data tags (MDTs) of all fields currently in 
the 3270 buffer are to be reset to a not— modified condition 
(that is, field reset) before any map data is written to 
the buffer. This allows the DFHMDF ATTRB specification for 
the requested map to control the final status of any fields 
written or rewritten in response to a DFHBMS macro 
instruction . 

PAGEOUT Ma cro 

In the DFHBMS TYPE=PAGEOUT macro, CTRL= specifies how pages are 
to be displayed at the terminal (when the disposition is OUT or 
STORE) and whether or not control is to be returned to the 
application program. 

PAGE 

specifies that pages are to be paged one at a time to the 
terminal. 3MS writes the first page to the terminal when 
the terminal becomes available or upon request of the 
operator. All subsequent pages are written to the terminal 
in response to a terminal operator request (see the 
description of paging commands in the CICS/VS Operator's 
Guide ) . If automatic paging was specified for the terminal 
at system generation, this specification overrides the 
automatic paging for this logical message. For TCAM SNA 
and VTAM— supported terminals, PAGE applies to all LDC page 
sets accumulated within the logical message. 

AUTOPAGE 

specifies that pages are to be paged automatically to the 
terminal. BMS writes each page of the logical message to 
the terminal when it becomes available. If paging upon 
request was specified for the terminal at system 
generation, this specification overrides it for this 
logical message, provided that the terminal is not a 3270 
video terminal (AUTOPAGE cannot be specified for a 3270 
video terminal) . For TCAM SNA and VTAM— supported 
terminals, AUTOPAGE applies to all LDC page sets 
accumulated in the logical message. 

A specification of PAGE for 3284 or 3286 devices is ignored. 
That is, AUTOPAGE is assumed for these devices. If neither 
PAGE nor AUTOPAGE is specified, the paging status specified for 
the terminal at system generation determines how pages are to 
be written to the terminal. For TCAM SNA and VTAM-supported 
terminals with LDC support, paging status for each LDC is 
obtained from the system LDC table. 



308 CICS/VS APRM (ML) 



RETAIN 

indicates that BUS is to return control to the application 
program for further processing after it has written the 
page(s) to the terminal and has received data other than a 
purge, copy, or paging command from the operator. 

RETAIN is intended to be used for a combination of page 
display from the page file (logical message built using the 
STORE disposition) and operator data entry. BMS issues a 
GET to the terminal after writing the appropriate page (s) 
to the terminal. BUS issues the GET only if the logical 
message was built with STORE disposition. If the logical 
message was not built with STORE disposition, BMS returns 
control to the application program after the last page is 
written to the terminal, and without issuing a GET to the 
terminal. 

The operator may enter any page, purge, or copy commands 
that are valid for the particular message. Any other 
entered data is passed back to the application program 
after the current message is purged. The address of the 
newly acquired TIOA is in TCTTEDA. A chaining command is 
not valid at this point because it requests the creation of 
a new task for the terminal to which a task is already 
attached. 

RELEASE 

indicates that control is to be returned to the program at 
the next higher logical level after BMS has written the 
page(s) to the terminal. When RELEASE is specified, LAST 
is assumed for TCAM SNA and VTAM— supported terminals, 
except when the PAGEOUT is for a route operation. 

N ote ; To ensure that a logical message appears at the 
receiving terminal at once, before any other transaction is 
initiated from the terminal and before any other messages 
that may have been routed to it, CTRL=RELEASE should be 
specified. 

If neither RETAIN nor RELEASE is specified, and STORE is the 
disposition for the logical message, a new task is scheduled by 
CICS/VS task control for writing the pages to the terminal, and 
control is returned to the application program at this time 
rather than after the pages are written. After the application 
program has terminated, the pages will be written to the 
terminal in response to terminal operator requests (see the 
description of paging commands in the CICS/VS Operato r's 
Gui de) . If pages are being routed, a specification of either 
RELEASE or RETAIN is ignored. 

| If messages are being chained, and the second transaction uses 

| BMS in paging mode, the use of RETAIN will prevent further 

| chaining. RELEASE must be used to allow more than two 

I transactions to be chained together. 



CORSOR= 



is used to position the cursor upon completion of a write 
operation to a 3270 device. This operand is valid in TYPB=0UT 
macros only when maps are used. 
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DATA = 



number 

is an integer indicating a particular position relative to 
zero on the screen; the range of values that may be 
specified depends upon the screen size of the 3270 being 
used. 

YES 

indicates that a value indicating the desired cursor 
position has been placed in TCABMSCP. (Note, though, that 
TCABMSCP may be used by CICS/VS for other purposes. The 
user should not rely on the cursor position specification 
remaining intact throughout a transaction.) 

This operand overrides the IC option of the ATTRB operand of 
the DFHMDP macro instruction, if it is specified in a macro 
that completes a pagebuilding operation and thus causes a write 
operation. Previous specifications' of the IC option and of the 
CURSOR operand for the other maps making up the page are 
ignored . 

Similarly, a CURSOR operand on a later TEXTBLD macro always 
overrides a CURSOR operand on an earlier TEXTBLD macro. 

An alternate method may be used to dynamically position the 
cursor on the output screen. This method is called symbolic 
cursor positioning (SCP). SCP allows a field in the TIOA to be 
marked, symbolically, such that the cursor is placed under the 
first data byte of the field on the output screen. 

Requirements for SCP use are as follows: 

• M0DE=IN0UT must be specified on the DFHMSD macro for maps 
and DSECTs which will be used with SCP. 

• CURSOR=YES must be specified on the DFHBMS macro. 

© Field TCABMSCP must be initialized with hexadecimal Fs; for 
example, MVC TCABMSCP, =X •FFFF» . (In COBOL move minus one 
into TCABMSCP which has been defined as PIC S9 (4) COMP.) 

• The length field, suffix "L", associated with the field 
under which the cursor is to be placed must be initialized 
with hexadecimal Fs. For example, MVC FIELD3L,=X , FFFF» . 

The remainder of the TIOA may be built as desired by the user. 
SCP is operable only for devices which allow cursor placement 
to be performed independent of data placement; for example, 
3604 and 3270. SCP specification is ignored for other devices. 



indicates one of the following three output mapping data 
selection modes. 

NO 

specifies that only default data is to be written from the 
selected map. 

YES 

specifies that data placed in the TIOA by the application 
programmer is to be merged with default data from the map. 
The user-supplied data and/or attribute character (3270 
only) supplied for a given field replaces the corresponding 
default data and/or attribute character from the map. 
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ONLY 

specifies that only data placed in the TIOA by the 
application programmer is to be written. The attribute 
characters (3270 only) must be specified for each field in 
the TIOA. any default data or attributes from the map are 
ignored. 

This operand is valid only when mapping is used. If it is 
omitted, DATA=N0 is assumed. The first position of each field 
in data placed in the TIOA by the application program must 
contain a non— null character. A suitable replacement character 
for a null character is a blank (X'40 1 ). 

EOC=symbolic address 

specifies the symbolic address of the routine to be given 
control if the reguest/response unit (RU) is received, during a 
BMS input operation, vith the end— of— chain indicator set. This 
operand is used only for VTAM interactive and batch logical 
units. 

EODPORG= 

specifies the manner in which CICS/VS deletes the current 
message. 

AUTO 

specifies that CICS/VS is to delete the message 
automatically if the operator enters a transaction that is 
not a paging command. Alternatively, the operator may 
delete the message with a purge command (see the CICS/VS 
Ope rator's Guide ) . 

OPER 

specifies that CICS/VS is not to delete the message until 
the terminal operator explicitly reguests deletion with a 
purge command. 

Note : If temporary storage is reinitialized, all messages are 
lost, regardless of any other specifications. 

EODS=symbolic address 

indicates the label of a user-written routine to receive 
control if end— of— data— set (EODS) has been received during a 
BMS input operation. If this condition occurs, no data has 
been received (only a standalone function management header) . 
No data is mapped and TCTTEDA is set to zero. This operand 
applies only to VTAM batch logical units. 

ERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if any of the response conditions except 
NORESP occurs. 

ERRTERM= 

indicates the terminal to be notified if the message is purged 
because it is undeliverable . The message number, title 
identification, and destination of the message are indicated. 

termid 

is the terminal identification of the terminal to be 
notified. 

Chapter 4.3. Basic Mapping Support 311 



OBIG 

indicates that the originating terminal is to be notified. 

YES 

indicates that the terminal identification of the terminal 
to be notified has been placed in TCAMSTI prior to issuing 
the DFHBMS TYPE=ROUTE macro instruction. 

This operand is operative only if the PRGDLAY operand was 
specified in the DFHSG PROGRAM=BMS macro instruction by the 
system programmer. If PRGDLAY was not specified, this operand 
has no effect. 

FMHPARM= 

specifies information to be included in a function management 
header (FMH) being transmitted to a 3650 logical unit. Refer 
to the CICS/VS 3650 Guide for details of the FMH and of 3650 
logical units. 

This operand applies only to VT AM— supported 3650 logical units 
with outboard formatting. It specifies the name of the map to 
be used with this BMS request. 

parameter 

specifies the eight— character name of the map. 

YES 

indicates that the map name has been stored in the eight- 
character TCAMSFMP field. 



HEADER= 



specifies that header data is to be placed at the beginning of 
each output page and points to that data. 

symbolic address 

is the symbolic address of the header record that will be 
used to place header information at the beginning of each 
page. 

YES 

indicates that the application programmer has placed the 
address of the header record in TCAMSHDR prior to issuing 
this DFHBMS macro instruction. 

If this operand is used in a DOS COBOL program, the label must 
not be longer than eight characters. 

The record pointed to by HEADER or TRAILER operands has the 
following format: 



I I I I I 

| LL | P | C | < — D ata PPPPP -> | 

III! I 



where: 
LL 



is a two— byte field containing the length of the header or 
trailer information. 
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is a one— byte field containing a character of the user's 
choice that indicates which, if any, are the embedded page 
number positions in the data area. The character chosen 
must, obviously, be one that does not otherwise appear in 
the data area. The embedded page number positions will 
initially contain this same character. The character must 
not be any of the following, which are reserved: X^OC 1 , 
X'15', XM7», X»26«, and X»FF«. If page-numbering is not 
required, P should be set to blank (X*40*) . 

C 

is a reserved one— byte field. 

Data and PPPPP 

is the header or trailer information to be placed at the 
beginning or end of each page of output. This information 
consists of a constant character string with, optionally, a 
page— number field of up to five characters embedded within 
it. 

The placement of the page— number field within the data area 
is entirely at the user's choice. If such a field is 
defined, BMS will place the current page number in it for 
each page built. The number is padded on the left with 
zeros if it does not fill the defined field; it is 
truncated on the left if it is too large for the defined 
field. Page numbering starts at 1 and can run up to 
32,767. It is automatically reset to 1 after each DFHBMS 
TYPE=PAGEOUT request or if the output disposition is 
changed. The legibility of the code will be improved if 
the page— number field is separated from the constant data 
by blanks or other suitable characters, though such 
separation is not required by BMS. 

New— line characters (XMS 1 ) may be included in the constant 
data if a multiple— line header or trailer is required. 

IGREQCD=symbolic address 

specifies the entry label of a user— written routine to which 
control is passed if an output operation is attempted after a 
signal command with a hard request change direction (RCD) code 
(X»00010000») has been received from an LUTYPE4 logical unit. 
Applies to output operations only. Valid in assembler language 
only. 

IGREQID=symbolic address 

specifies the entry label of a user-coded routine to which 
control is to be passed if the prefix specified is different 
from the established (via a previous specification or default) 
REQID for this logical message. 



INTRVAL= 



specifies the interval of time after which data being routed to 
the page file is to be transmitted to the terminal (s). 

numeric value 

is of the form HHMMSS, where HH represents hours from 00 to 
99, MM represents minutes from 00 to 59, and SS represents 
seconds from 00 to 59. 
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IBS 

indicates that the interval of time has been placed in 
packed decimal form (0HHMMSS+) in TCAMSRTI prior to issuing 
the DFHBMS TTPE=ROUTE macro instruction. 

INVET=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if the terminal identification specified by 
the ERRTERM operand of a DFHBMS TYPE=ROUTE macro instruction is 
invalid or is assigned to a terminal of a type not supported 
under BUS. 

INVLDC=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if the LDC mnemonic specified by the LDC 
operand does not appear in the LDC list associated with the 
TCTTE. 

INVMPSZ=symbolic address 

specifies the entry label of the user-written routine to which 
control is to be passed if (1) the specified map is too wide 
for a receiving terminal, or (2) OFLOW has been requested and 
the specified map is too long for the receiving terminal. Upon 
entry to the user-written routine, TCAMSRI1 contains a terminal 
code that further identifies the receiving terminal (see 
"Terminal Code (TC) Table," earlier in this chapter) . 

INVREQ=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if the request for BMS services is invalid. 

This response may be caused by any of the following conditions: 

• Changing the disposition of a routed logical message prior 
to its completion, through DFHBMS TYPE=PAGEOUT 

• Issuing a separate TYPE=TEXTBLD or TYPE=PAGEBLD request to 
the direct (originating) terminal while in the process of 
building a routed logical message 

• Mixing TYPE=TEXTBLD and TYPE=PAGEBLD requests when building 
a logical message 

• Specifying NOEDIT with a TYPE=PAGEBLD or TYPE=TEXTBLD 
request 

• Specifying the TRAILER operand with TYPE=PAGEOUT when 
terminating a logical message built using TYPE=PAGEBLD 
req ue st s 

• Issuing a DFHBMS request with DATA=YES or DATA=NO and 
specifying a map with no field specifications 

• Issuing a DFHBMS reguest with TYPE=STORE from a CICS/VS 
application program communicating with a host 
conversational (3653) logical unit. 

JUSTIFY= 

describes the positioning of the text data. 
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LDC= 



FIRST 

indicates that this TEXTBLD data is to be positioned at the 
top of the page. Any partially formatted page from 
preceding DFHBMS requests is considered to be complete. If 
the HEADER operand is specified, the header precedes the 
TEXTBLD data. 

LAST 

indicates that this TEXTBLD data is to be positioned at the 
bottom of the page. If the TRAILER operand is specified, 
the trailer appears after the TEXTBLD data. The page is 
considered to be complete after the request is processed. 

line number 

indicates that this TEXTBLD data is to be positioned at 
line nnn of the page. 

YES 

indicates that the application programmer has placed a 
binary value from 1 to 255 in TCAMSJ prior to issuing this 
DFHBMS TYPE=TEXTBLD macro instruction. A value in the 
range from 1 through 240 represents a line number; 254 
represents LAST; and 255 represents FIRST. The values from 
241 through 253 are reserved and should not be specified. 



specifies the mnemonic to be used by CICS/VS to determine the 
logical device code that is to be used for the BMS operation 
and transmitted in the function management header (FMH) to the 
logical unit. This operand is meaningful only for TCAM and 
VTAM terminals with LDC support. 

mnemonic 

is the two— character mnemonic used to determine the 
appropriate LDC numeric value. The mnemonic represents an 
LDC entry in the DFHTCT TYPE=LDC macro instruction. 
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LIST= 



YES 

indicates that the application program has placed the LDC 
mnemonic in TCAMSLDM. 

When an LDC is specified, BMS uses the device type, the page 
size, and the page status associated with the LDC mnemonic to 
format the message. These values are taken from the extended 
local LDC table for the LO, if it has one. If the LO has only 
a local (unextended) LDC table, the values are taken from the 
system LDC table. The numeric value of the LDC is obtained 
from the local LDC table, unless this is an unextended table 
and the value is not specified, in which case it is taken from 
the system table. 

If the LDC operand of the DFHBMS macro is omitted, the LDC 
mnemonic specified in the DFHMSD macro is used, (except in 
TEXTBLD operations, when maps do not apply). If the LDC 
operand has also been omitted from the DFHMSD macro, the action 
depends on the type of the logical unit. 

For a 3601 LU, the first entry in the local or extended local 
LDC table is used, if there is one. If a default cannot be 
obtained in this way, a null LDC numeric value (X"00*) is used. 
The pagesize used is the value that was specified in the DFHTCT 
TYPE=TERMINAL macro, or (1,40) if such a value was not 
specified . 

For a batch or batch data interchange LU, the local LDC table 
is not used to supply a default LDC; instead, the message is 
directed to the LU console (that is, to any medium that the LU 
elects to receive such messages. Note that for a batch data 
interchange LU, this does not imply sending an LDC in an FMH) . 
The pagesize is obtained in the manner described for the 3601 
LU. 

For DFHBMS TYPE=ROUTE operations, the LDC operand of the ROUTE 
macro takes precedence over all other sources. If this operand 
is omitted and a route list is specified (LIST=symbolic address 
or YES) , the LDC mnemonic in the route list is used; if the 
route list contains no LDC mnemonic, or no route list is 
specified, a default LDC is chosen as described above. 



specifies the terminals and/or operators to which paged data is 
to be directed. 

symbolic address 

is the label of a list of terminals and/or operators to 
which data is to be directed. If this parameter is used on 
a DOS COBOL program the label must not be longer than eight 
characters. 



YES 



ALL 



indicates that the address of the list of terminals and/or 
operators to which data is to be directed has been placed 
in TCAMSRLA prior to issuing the DFHBMS TYPE=ROUTE macro 
instruction . 



indicates that all terminals supported by BMS are to 
receive the paged data. 



The list of destination terminals and/or operators consists of 
16-byte entries as follows: 
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Bytes Contents 

1—4 contain a four— character (including trailing 

blanks) terminal or logical unit identification, 
or blanks 

5—6 contain the two-character LDC mnemonic for TCAM 

and VTAM— supported terminals with LDC support, or 

blanks 

7—9 contain the operator identification, or blanks 

10 serve as a status flag for the route entry (see 

"Status Flag Byte in User— Supplied Route List," 
earlier in this chapter.) 

11—16 reserved; must contain blanks 

The end of the list is designated as follows: 

Assembler: DC AL2 (-1) 

COBOL: PIC S9 (4) COMP VALUE -1. 

PL/I: DECLARE FIXED BINARY (15) INITIAL (-1) ; 

It may be necessary for the application program to supply this 
list of destinations in noncontiguous areas called segments. 
If the list is supplied in segments, every segment except the 
last is terminated with (at least) an eight— byte entry as 
follows: 



Bytes Contents 
1-2 

Assembler: DC AL2 (-2) 

COBOL: PIC S9(4) COMP VALUE -2. 

PL /I: DECLARE FIXED BINARY (15) INITIAL (-2) ; 

3-4 reserved 

5—8 contain the chain address to the first entry of 
the next segment 

The end of the list is designated as described above for an 
unsegmented list. 

If, for any entry in the list, 

1. The terminal identification is specified but the operator 
identification is omitted, the data is route d to that 
terminal without regard to operator identification. 

2. The operator identification is specified but no terminal 
identification is given, the data is routed to the •first 1 
terminal at which the operator is signed on under the 
specified operator identification. The 'first 1 is 
determined by the physical location of the terminal entry 
in the CICS/VS terminal control table. If no operator is 
signed on under the specified operator identification when 
the DFHBMS TYPE=ROUTE macro instruction is executed, the 
route list entry is ignored. 
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HAP= 



HAPADR= 



3. Both terminal identification and operator identification 
are specified, the data is routed to that terminal. 

For either 2 or 3 above, the data is displayed only if the 
operator with the specified identification is signed on at the 
terminal when the data is ready to be displayed, or when the 
operator signs on after the data is ready to be displayed. 
Entries of all three types may be included in one segmented or 
unsegmented list. 

It should be noted that the status flag in each route list 
entry is used to notify the application program of certain 
status conditions for that requested destination. Therefore, 
if the route list is contained within the application program 
and BUS alters the status flag, the application program can no 
longer be considered reentrant. 



specifies the name of the map to be used when mapping formatted 
pages. 

map name 

is the one— to seven— character name of the map within a map 

set . 

YES 

indicates that the application programmer has placed the 
name of the map in TCABMSMN prior to issuing this DFHBHS 
macro instruction. The name must be left— justified and 
padded with trailing blanks to eight characters. 

Note ; Because map sets did not exist in pre— VS BHS , pre— VS 
application programs will not specify a MAPSET or MSETADR 
parameter. In this case, BUS takes the name specified in the 
HAP operand as the name of the map set. It does not suffix 
this name with a terminal type suffix, as described under the 
DFHHSD macro instruction, because the concept of device- 
dependent map sets was also inapplicable in pre— VS BHS. 



specifies the address of the map to be used when mapping 
formatted pages. This operand is valid only when the map has 
been coded within an assembler— language program. 

symbolic address 

is the one— to seven-character symbolic label that has been 
assigned to the map. 

YES 

indicates that the application programmer has placed the 
address of the map in TCABHSHA prior to issuing this DFHBMS 
macro instruction. 

If HAPADR is specified, HAP, HAPSET, and MSETADR should not be 
used. 
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MAPFAIL=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if the data to be mapped has a length of zero 
or does not contain a SBA (start buffer address) sequence. 
This response can occur only if TYPE=IN or TYPE=MAP is 
specified and data is mapped from a 3270 device. For TYPE=IN, 
the address of the erroneous TIOA is available at TCTTEDA. For 
TYPE=MAP, this address is wherever the user placed it prior to 
the request (either in TCTTEDA or TCAMSIOA) . . 



MAPSET= 



specifies the name of the map set to be used in the mapping 
operation . 

map set name 

is the one— to seven— character name of the map set. 

YES 

indicates that the application programmer has placed the 
name of the map set in TCAMSMSN prior to issuing the DFHBMS 
macro instruction. The name must be left— justified and 
padded with trailing blanks to eight characters. 

The map set established by this operand must reside in the 
CICS/VS program library, and a corresponding entry for the map 
set must exist in the processing program table (PPT) . 

If MAPSET is coded, MAP must also be coded. 

MSETADR= 

specifies the address of the map set to be used in the mapping 
operation. This operand is valid only when the map has been 
coded within an assembler— language program. 

symbolic address 

is the one— to eight— character symbolic label that has been 
assigned to the map set. 

YES 

indicates that the application programmer has placed the 
address of the map set in TCAMSMSA prior to issuing this 
DFHBMS macro instruction. 

MiPSET and MSETADE are mutually exclusive operands. If MSETADR 
is coded, MAP must also be coded. 

NORESP=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if none of the other response conditions 
(whether checked for or not) occurs. NORESP signifies "normal 
response." 

0FL0W=symbolic address 

specifies the symbolic address of a routine to which control is 
to be transferred if the mapped data does not fit on the 
current page (see "PAGEBLD Overflow Processing, »» earlier in 
this chapter) . 



0PCLASS= 



specifies the operator class (es) to which data is to be routed. 
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decimal value,... 

consists of one or more decimal values in the range from 1 
through 24, separated by commas, specifically identifying 
the operator class (es) . 

YES 

indicates that values identifying operator classes have 
been placed in TCAMSOC (three— byte field) prior to issuing 
the DFHBMS TYPE=ROUTE macro instruction. 

A bit position corresponding to each value from 1 through 24 is 
established in a three— byte field which is matched against the 
three— byte operator class field in the CICS/VS terminal control 
table terminal entry (TCTTEOCL) for a terminal. At least one 
pair of corresponding bits must match in order for the message 
to be routed to the terminal. The value in TCTTEOCL is set 
during sign— on according to the OPCLASS operand of the DFHSNT 
TYPE=ENTRY macro instruction specified by the system 
programmer. 

If data is to be routed to an operator class, the application 
programmer may do one of the following: 

1. Specify OPCLASS and omit LIST. Data is routed to each 
terminal at which an operator is signed on with the 
specified OPCLASS at the time the DFHBMS macro instruction 
is issued. 

2. Specify OPCLASS and LIST=ALL. Data is routed to all 
terminals. 

In both cases, the data is not displaye d on a terminal until an 
operator is signed on with the specified OPCLASS. In general, 
LIST=ALL is specified with OPCLASS only when it is anticipated 
that someone will eventually sign on with the specified OPCLASS 
at every supported terminal. 

If the application programmer specifies OPCLASS and 
LIST=symbolic address, and the list contains operator 
identifications, a specified operator identification overrides 
OPCLASS for that entry. 
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PROPT=NLEOM 

requests BMS to build a logical message specifically for a 3270 
printer or a 3270 display with the Printer Adapter Feature. If 
used, this operand must be specified in the first DFHBMS macro 
for each logical message. If routing, this operand must be 
specified on the TYPE=ROUTE request. Specification of this 
operand overrides the CTRL operand, if present; 
CTRL= (PRINT, HONEOM,FREEKB, PRESET) is assumed. 

Specification of this operand will cause the page to be 
formatted using new line (NL) characters as for the other hard 
copy devices. An end— of-message (EM) character is placed at 
the end of the data. As the data is printed, a new line 
character causes printing to continue on the next line. The 
end— of— message character terminates printing. The next print 
operation will start on a new line. 

The following restrictions apply when using this parameter: 
Buffer updating and attribute modification of fields previously 
written into the buffer are not allowed. BMS issues an ERASE 
with every write to the terminal. 

When building a logical message, BMS will insert a new line 
(NL) character at the end of each line and an end— of— message 
(EM) character at the end of the text. Each NL and the EM 
character occupies a 3270 buffer position; therefore, to avoid 
possible wrap-around due to excessive data in the buffer, the 
PGESIZE values defined in the DFHTCT system macro should be 
such that the remainder of the 3270 buffer will contain these 
additional characters. 

This operand is ignored if the direct or a routing terminal is 
not a 3270 printer or display with the Printer Adapter Feature. 



RDATT= 



REQID= 



specifies the address of a routine to receive control if the 
operator presses the ATTN key on a 2741 when input is being 
entered from the terminal in response to a DFHBMS TYPE=IN 
request. This operand can be specified only if 2741 Read 
Attention support, an option available under either CICS/DOS/VS 
or CICS/OS/VS, has been generated into the system (see "2741 
Read Attention and Write Break Support" in Chapter 4.2). 



specifies the prefix to be used with the temporary storage 
identification. The identification (including the prefix) is 
used by CICS/VS when attempting message recovery. 

BMS message recovery is provided for a logical message only if 
the STORE operand is specified in the BMS output request and if 
the logical end of task has been reached. 

Only one prefix can be specified for each logical message. If 
the REQID operand is not specified, CICS/VS assigns the prefix 
** (two asterisks) . 

prefix 

indicates the alphanumeric prefix to be used as the first 
two characters of a temporary storage identification. 
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YES 

indicates that the prefix has been stored at TCAMSRID. 

RETPAGE=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if one or more completed pages are returned 
to the application program. This response can occur only if 
TYPE=RETURN is specified in the DFHBMS macro instruction (see 
the description of TYPE=RETURN for further information) . 

RTEFAIL=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if a DFHBMS TYPE=ROUTE request results in a 
null routing environment (that is, the message will be sent, by 
default, to only the originating terminal) . (To determine why 
route list entries were skipped, refer to "Status Flag Byte in 
User— Supplied Route List", earlier in this chapter.) 

RTESOME=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed if (1) some of the entries in the user- 
specified route list named in the LIST operand of a DFHBMS 
TYPE=ROUTE macro instruction are excluded from the routing 
environment, or (2) LIST=ALL is specified and not all of the 
entries in the terminal control table are included in the 
routing environment. (To determine why some route list entries 
were skipped, refer to "Status Flag Byte in User— Supplied Route 
List", earlier in this chapter.) 



TIME= 



TITLE= 



specifies the time of day at which data being routed to the 
page file is to be transmitted to the terminal (s) . 

numeric value 

is of the form HHMMSS, where HH represents hours from 00 to 
99, MM represents minutes from 00 to 59, and SS represents 
seconds from 00 to 59. 



YES 



indicates that the time of day has been placed in packed 
decimal form (0HHMMSS+) in TCAMSRTI prior to issuing the 
DFHBMS TYPE=ROUTE macro instruction. 



specifies the symbolic address of a record that contains a 
title to be associated with the logical message created under 
this routing environment. 

symbolic address 

is the symbolic address of the title length field that 
precedes the title in the title record. If this parameter 
is used in a DOS COBOL program the label must not be longer 
than eight characters. 



322 CICS/VS APRM(ML) 



YES 

indicates that the address of the title length field in the 
title record has been placed in TCAMSTA prior to issuing 
the DFHBMS TYPE=ROUTE macro instruction. 

The title pointed to by the TITLE operand is displayed with the 
logical message ID whan the terminal paging query command is 
entered (see the CICS/VS Operator's Guide) . This title serves 
as an additional message identifier, displayed upon request 
with the message ID, not on the logical message. The value in 
the two-byte length field preceding the title includes the 
bytes used for the length field. The length field and title, 
in total, may be up to 64 bytes long. For example: 

^•OOIA* |MONTHLYj*INVENTORY#REPORT| 



2-byte 24-byte 

length title field 
field 

TRAILER= 

specifies that user— defined trailer data is to be placed at the 
foot of each page completed by the TEXTBLD macro in which the 
operand is coded, or at the foot of the last page if the 
operand appears on a PAGEOUT macro. The operand is ignored if 
no page is completed by the macro in which it appears. The 
operand is invalid in a PAGEOUT macro that is completing a 
message built using PAGEBLD macros; if TRAILER= is used in such 
circumstances, BBS returns an INVREQ return code. 

The format of trailer data is the same as that for header data, 
described above (see ,, HEADER=") . Page numbering can be 
accomplished automatically, as with header data. 

symbolic address 

is the symbolic address of the trailer record that will be 
used to place trailer data at the bottom of the last page. 
If this parameter is used in a DOS COBOL program, the label 
must not be longer than eight characters. 

YES 

indicates that the application programmer has placed the 
address of the trailer record in TCAMSTRL prior to issuing 
this DFHBMS macro instruction. 

TRANSID=transaction code 

specifies a one— to four-character transaction identification 
to be used with the next input message entered from the 
terminal to which this task is attached. 

This operand is valid only when CTRL=RELEASE is specified. 

TSIOERR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an unrecoverable temporary storage 
input/output error occurs. 
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TYPE= 



The following TYPE= parameters distinguish macro instructions 
with distinct purposes. As such, they are not treated as 
operands and so described in this section; instead, they are 
explained individually in earlier sections in this chapter. 



CHECK 


PAGEOUT 


IN 


PURGE 


MAP 


ROUTE 


PAGEBLD 


TEXTBLD 



The SAVE and TEXT parameters have special meaning for TYPE=IN 
(both) and TYPE=MAP (SAVE only) macros, and are described with 
the individual macros. 

The following four TYPE= parameters indicate the disposition of 
output data: 

OUT 

indicates that the output is to be written to the 
originating terminal when the page is complete. 

Once a DFHBHS macro with OUT disposition has been issued, 
the application program must not issue a DFHSC 
TYPE=FREEMAIN,RELEASE=ALL macro until either a DFHBMS 
TYPE=PAGEOUT or DFHBMS TYPE=PURGE macro has been issued. 

When the OUT parameter is not preceded by either PAGEBLD or 
TEXTBLD, it effectively distinguishes a macro with a 
different purpose. This usage is described earlier in this 
chapter under the heading "Direct Output (TYPE=OUT) ." 

RETURN 

indicates that the complete page (s) is to be returned to 
the application programmer. (See "Handling Returned 
Pages," earlier, for further information.) The application 
program regains control (1) immediately following the BMS 
instruction if the current page is not yet completed, or 
(2) at an alternative entry point specified through the 
RETPAGE operand of this macro instruction if one or more 
pages have been completed. 

STORE 

indicates that the output is to be placed in temporary 
storage to be displayed in response to paging commands 
entered by the terminal operator (for more information 
about these commands, see the CICS/VS Op erator's G uide ) . 
If STORE is specified with a REQID that is defined in the 
Temporary Storage Table (TST) , CICS/VS provides message 
recovery for logical messages if the task has reached 
logical end. The CICS/VS Temporary Storage facility is 
needed to hold messages awaiting delivery to terminals. 

WAIT 

indicates that BMS is to wait until all output operations 
are complete before returning control to the application 
program. WAIT must be specified with every output request 
except the following: 
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— The last output request prior to task termination 

— The last output request prior to an input operation 

— The last output request prior to issuing a DPHBMS 
TYPE=PAGBOUT macro instruction that precedes task 
termination or an input operation 

If no disposition is specified, the output is sent to the 
originating terminal. Once the disposition has been 
established for a logical message, it is not necessary to 
repeat the disposition for that logical message. Any change of 
disposition specified while in the process of building a 
logical message forces that logical message to completion with 
its original disposition. Then a new logical message is 
started with a new disposition. The disposition parameter is 
handled differently under DPHBMS TYPE=ROUTE (see "Disposition 
and Message Routing") . 

The remaining TYPE= parameters are: 

ERASE 

specifies that a 3270 buffer or 3604 screen is to be erased 
before this page of output is displayed. A printer buffer 
will contain meaningless data from prior messages if all 
positions are not filled with current data. The first 
output operation in any transaction, or in a series of 
pseudo— conversational transactions, should always specify 
ERASE. For transactions attached to 3278 screens, this 
will also ensure that the correct screen size is selected 
as defined for the transaction in the PCT. 

ERASEAUP 

specifies that all unprotected character locations in a 
3270 buffer are to be erased before this page of output 
data is displayed. There are no further effects of 
specifying this parameter. 

LAST 

signals to CICS/VS that this is the last output for a 
transaction and, therefore, the end of a bracket operation. 
This operand is meaningful only for TCAM SNA terminals and 
for VTftM-supported terminals and is applicable only when 
00T is the specified disposition. Por TCAM, an indicator 
is set in the communication control byte (CCB) requesting 
that the message handler send end-of -bracket . 

NOEDIT 

specifies that CICS/VS need not insert device— dependent 
control characters (carrier return, line feed, idle 
characters, and so on) into the output data stream. The 
application program, therefore, assumes responsibility for 
providing any required control characters. This parameter 
| is ignored for all output operations specifying maps. This 

I parameter cannot be used with 3601 devices. 

SAVE 

specifies that the user-supplied data area addressed by 
TCTTEDA or TCAMSIOA is to be saved. The location 
containing the address of the data area will be changed by 
BHS, so the address should be stored elsewhere before 
issuing the macro . 
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WRBBK- 

is used to specify the action that is to occur if the ATTN key 
on a 2741 is pressed while data is being written to the 
terminal. 

symbolic address 

specifies the symbolic address of the routine to receive 
control when the ATTN key on a 2741 is pressed during the 
actual write to the terminal. This operand is operative 
when 2741 Write Break support has been generated into 
CICS/VS (available only under OS/VS) and when the task 
would normally have regained control. It is not valid on 
BBS macros where TYPE=STORB or TYPE=RETURN is specified, or 
on a PAGEOUT macro when CTRL=RELEASE is specified. 

CURRENT 

specifies that transmission of the current page to the 
terminal is to cease, but, if autopaging has been 
requested, transmission of the next page (if any) begins. 

ALL 

specifies that transmission of the current page to the 
terminal is to cease and that no additional pages are to be 
transmitted. The logical message is purged. 

Both CURRENT and ALL are meaningful only if 2741 Write Break 
support has been generated into CICS/VS (available only under 
OS/VS) , and if TYPE=STORE was specified in preceding DPHBMS 
reguests, or data has been sent to terminals other than the 
originating terminal. In these cases, data has been placed in 
temporary storage and is being displayed by a program other 
than the one associated with the originating terminal. 
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Chapter 4.4. Batch Data Interchange (DFHDI Macro Instruction) 



The CICS Batch Data Interchange program provides for communication 
between an application program and a named data set (or destination) or 
a selected output medium. The named data set (or destination) must be 
part of a batch data interchange logical unit in an outboard controller; 
the selected output medium must be part of either such a logical unit or 
an LUTYPE4. The term "outboard controller" is a generalized reference 
to a programmable subsystem, such as the IBM 3770 Data Communication 
System or the IBM 3790 Data Communication System, which uses SNA 
protocols. (Details of SNA protocols and the data sets that can be used 
are given in the CICS/VS 3767. 3770 and 6670 Guide and the C ICS/VS 3790 
G uide . ) 

The batch data interchange macro instruction (DFHDI) is used to 
specify ADD, ERASE, REPLACE, QUERY, END, ABORT, SEND, RECEIVE, and CHECK 
operations on data sets in an outboard controller. Where the controller 
is an LUTYPE4 logical unit, only the END, ABORT, SEND, RECEIVE and CHBCK 
operations are supported. 

The DFHDI macro instruction can be used only with assembler language 

application programs. It is not available for COBOL or PL/I programs, 

which must use the command level interface if they require these 
facilities. 



Addition of Records to a Data Set (TYPE=ADD) 



The format of the DFHDI macro instruction to add records to a data set 
is as follows: 




TYPE=(ADD[ , fSAVEI NOSftVB l ][ , {WAIT | NOW A IT} )) 

,DNADDR= {symbolic address | YES} 
[ ,NUMREC= {integer | YES} ] 
[ ,DEFRESP=YES] 

[ ,VOLADDR= {symbolic address|YES} ] 
[ ,NORESP=symbolic address] 
[ ,F0NCERR=symbolic address] 
[ ,SELNERR=symbolic address] 
[ ,UNEXPIN=symbolic address] 



This macro specifies that a record in the current TIOA, as indicated 
by the TCTTEDA, is to be added to the sequential or keyed direct data 
set corresponding to the destination name specified in the DNADDR 
operand. 

| The SAVE parameter specifies that the contents of the TIOA is to be 
| saved; however, there is no guarantee that TCTTEDA will remain 
I unchanged . 

The WAIT parameter indicates that task activity is to be suspended 
until the DFHDI macro has been executed. 
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Deletion of Records from a Data Set (TYPE=ERASE) 



The format of the DFHDI macro instruction to delete records from a data 
set is as follows: 



TTPB= (BR ASB[ , f WAIT I HOWAIT} ]) 
,DNADDR= {symbolic address|YES} 
{,KEYADDR= {symbolic address| YES} |,RRNADDR= 

{record-id | YES}} 
[ ,DEFRESP=YES] 

[ ,VOLADDR= {symbolic address|YES} ] 
[ ,NORESP=symbolic address] 
[ ,FUNCERR=symbolic address] 
[ ,SELNERR=symbolic address] 
[ ,UNEXPIN=symbolic address] 



This macro specifies that a record, identified by the KEYADDR or 
RRNADDR operand, is to be deleted from the keyed direct data set 
corresponding to the destination name specified in the DNADDR operand. 

The WAIT parameter indicates that task activity is to be suspended 
until the DFHDI macro has been executed. 




328 



CICS/VS APRM(ML) 



Replacement of Records in a Data Set (TYPE = REPLACE) 

The format of the DFHDI macro instruction to replace records in a data 
set is as follows: 




TYPE=(REPLACE[ , SAVE | NOSAVE} ][ , {WAIT | NOWAIT} ]) 
,DNADDR= {symbolic address |YES} 
{,KEYADDR= {symbolic address|YES} |,RRNADDR= 

{record-id | YES}} 
[ ,NUMREC= {integer |YES} ] 
[ ,DEFRESP=YES] 

[ ,VOLADDR= {symbolic address|YES} ] 
[ ,NORESP=symbolic address] 
[ ,FUNCERR=symbolic address] 
[ ,SELNERR=symbolic address] 
[ ,UNEXPIN=symbolic address] 



This macro specifies that a record identified by the RRNADDR xor 
KEYADDR operand, in the current TIOA, is to replace a record in the 
addressed direct data set corresponding to the destination name 
specified in the DNADDR operand. 

Where more than one record is to be replaced, the second and 
subsequent records are replaced consecutively, starting with the one 
specified in the RRNADDR or KEYADDR operand. The number of records to 
be replaced is specified in the NUMREC operand. 

| The SAVE parameter specifies that the contents of the TIOA are to be 
| saved; however, there is no guarantee that TCTTEDA will remain 
| unchanged. 

The WAIT parameter indicates that task activity is to be suspended 
until the DFHDI macro has been executed. 
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Interrogation of Data Set (TYPE=QUERY), 



The format of the DFHDI macro to interrogate a data set is as follows: 




TYPE=QUERY 

,DNADDR= {symbolic address | YES} 
[ ,VOLADDR= {symbolic address|YES} ] 
[ ,NORESP=symbolic address] 
[ ,FUNCERR=symbolic address] 
[ ,SELNERR=symbolic address] 
[ ,UNEXPIN=symbolic address] 



This macro specifies that the name of the data set corresponding to 
the destination name specified in the DNADDR operand is to be solicited 
to allow the outboard batch program to transmit the data set to the 
host. The program must issue input requests to receive the records from 
the data set. 



Termination of Operations on a Data Set (TYPE=END) 

The format of the DFHDI macro to terminate operations on a data set is 
as follows: 



TYPE=END 

{ {, DNADDR= {symbolic address | YES) } 

| f , SELECT= f ( CONSOLE I PRINT I CARD I WPMBDI A 1 I WPMED IA2 

WPHEDIA3|WPHEDIA4[ ,nn]) |YES}}} 
[ ,VOLADDR= {symbolic address | YES) ] 
[ ,NORESP=symbolic address] 
[ ,FUNCERR=symbolic address] 
[ ,SELNERR=symbolic address] 
[ ,UNEXPIN=symbolic address] 




This macro specifies that operations on a data set are to be 
terminated normally. The current outboard destination is de-selected 
normally. 
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Abnormal Termination of Operations on a Data Set (TYPE=ABORT) 

The format of the DFHDI macro to terminate operations abnormally is as 
follows: 



TYPE=ABORT 

{ { ,DNADDR= {symbolic address | YES} } 

| {, SELECT= { (CONSOLE | PRINT | CARD | WPMEDIA 1 1 WPMEDIA2 | 

WPMEDIA3|WPMEDIA4[,nn]) |YES}}} 
[ ,VOLADDR= {symbolic address|YES) ] 
[ ,NORESP=symbolic address] 
[ ,FUNCERR=symbolic address] 
[ ,SELNERR=symbolic address] 
[ r UNEXPIN=symbolic address] 




This macro specifies that operations on a data set are to be 
terminated abnormally. The current outboard destination is de— selected 
abnormally. 



Transmission of Data from Host to Output Devices (TYPE = SEND) 

The format of the DFHDI macro instruction to send data to an output 
device controlled by a logical unit is as follows: 



TYPE= (SEND[ , {SAVE | NOSAVE) ][ , {WAIT | NOWAIT) ]) 

{{,DNADDR= {symbolic addressj YES) } 

| f ,SELECT=f ( CONSOLE I PRINT I CARD I WPMEDIA1 IWPMEDIA21 

WPMEDIA3|WPMEDIA4[,nn]) |YES}}} 
[ , VOLADDR= {symbolic address|YES) ] 
[ ,DEFRESP=YES] 
[ ,FUNCERR=symbolic address] 
[ ,SELNERR=symDolic address] 
[ ,UNEXPIN=symbolic address] 
[ ,NORESP=symbolic address] 




Data for an output medium is transmitted to the logical unit from the 
TIOA, as indicated by the TCTTEDA. The SAVE parameter indicates that 
| the TIOA is to be saved; however, there is no guarantee that TCTTEDA 
| will remain unchanged. 

The WAIT parameter indicates that task activity is to be suspended 
until the previous DFHDI macro has been executed. 
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Transmission of Data from Data Set to Host (TYPE = RECEIVE) 

The format of the DFHDI macro to enable the host to accept records is as 
follows: 



DFHDI | TYPE=(RECEIVE[ , {SAVE | NOSAVE) ]) 

| [ , NORESP=symbolic address] 

| [ ,EODS=symbolic address] 

| [ ,DSSTAT=symbolic address] 

| [ ,UNEXPIN=symbolic address] 

I 

i i 

This macro specifies that DPHTC TYPE=READ macro instructions are to 
be generated to obtain records from the inbound data stream. These 
records are returned to the application program in a TIOA addressed by 
TCTTEDA. The number of records returned by the TYPE=READ macro depends 
upon whether the chain assembly or logical read options have been 
specified by the system programmer, which in turn depend upon the data 
format transmitted by the outboard controller. 

When an FMH is encountered it is removed from the data stream and a 
response code is set to inform the application program of the change in 
destination selection status (see "Response Codes" later in this 
chapter) . 

When the FMH is for BEGIN or RESUME DESTINATION, and no data is 
obtained from the READ, a further READ is issued so that the request can 
complete with user data. 

When the FMH is for SUSPEND, END or ABORT destination, the data, if 
present, is presented first to the application program with a normal 
response code; on the next request, the appropriate response code is 
set. The response code indicating the change of destination status is 
presented to the application program with no user data. If a name was 
sent, TCADIDNA is set, on completion of each request, to point to a 
field describing the host destination as a one byte length field 
followed by the destination name. If no destination name was sent, the 
field TCADISEL is set to the medium and sub-address sent. For 
descriptions of the formats and codes used, see the desciption of the 
SELECT operand later in this chapter. 

When reading from multiple data sets on an LUTYPE4, the DSSTAT 
condition will be raised by any attempted read after an end-of— data— set 
FMH has been received. The condition indicates that the logical unit 
has currently no more data to send. 

The SAVE operand specifies that the contents of the TIOA are to be 
| saved; however, there is guarantee that the TCTTEDA will remain 
| unchanged. 
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Obtaining the Relative Record Number of Next Record (TYPE=NOTE) 



The format of the DFHDI macro to return the relative record number of 
the next record is as follows: 




TYPE=NOTE 

,DNADDR={symbolic address |IES} 
[ ,VOLADDR= {symbolic address| YES} ] 
[ ,NORESP=symbolic address] 
[ ,FUNCERR=symbolic address] 
[ ,SELNERR=symbolic address] 
[ ,UNEXPIN=symbolic address] 



This macro specifies that the relative record number of the position 
in the data set of the next available record is to be returned to the 
application program in a fullword field whose address is placed in the 
TCA at TCADIRNA after execution of the macro. The outboard destination 
is a user— defined addressed direct data set. 



Suspension of Execution of Task (TYPE = WAIT) 



The format of the DFHDI macro to suspend the execution of a task is as 
follows: 



DFHDI ) TYPE=WAIT 



This macro specifies that task activity is to be suspended until the 
previous DFHDI macro has been executed. This macro is meaningful only 
following a DFHDI TYPE=ADD, TYPE=ERASE, TYPE=REPLACE or TYPE=SEND. 
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Testing Response to a Request for Data Interchange Services (TYPE = CHECK) 



The format of the DFHDI macro to test the response code for a request 
for data interchange services is as follows: 




TTPE=CHECK 

[ , NORESP=symbolic address] 
[ ,EODS=symbolic address] 
[ ,DSSTAT=symbolic address] 
[ ,FUNCERR=symbolic address] 
[ ,SELNERR=symbolic address] 
[ ,UNEXPIN=symbolic address] 



This macro specifies that the response code from the previous DFHDI 
macro is to be tested and, where necessary, a branch made to the user- 
written routine whose address is specified in one of the following 
operands: NORESP, EODS, DSSTAT, FUNCERR, SBLNERR, or UNEXIN . 
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Batch Data Interchange Response Codes 

Response codes are grouped into categories according to the operands. 
Each category is given a code, for example NORESP has category code 
X^OO 1 which is placed in field TCADIRC1 in the TCA. Each category is 
subdivided into response codes that indicate the success or failure of a 
specified operation, for example "End destination FMH received" in 
category X , 04 i is 11. These response codes are placed in field TCADIRC2 
in the TCA. 

The categories, operands, response codes and their causes are shovn 
in Figure 4.4— 1. 



i i i r i 

1 Category 1 Operand | Condition 1 Response 1 


III 1 Code 1 


I X'OO* | NORBSP | Successful | 00 | 
I j j Begin destination FMH received | 01 | 
j j | Resume destination FMH received | 02 | 


lii i I 

| X , 04» | DSSTAT,EODS | End destination FMH received | 11 | 
I | | Suspend destination FMH received! 12 j 
| | | Abort destination FMH received | 13 | 
| | | Currently no data to send | 15 | 


I X^ 1 | FUNCERR | Request invalid for data set | | 
I | | organization I 21 j 
| | | Record too long | 22 | 
j | | Data set full I 23 | 
| | | Invalid keyword or record j | 
I | | identifier I 24 | 
| | | Resource not available | 25 | 
I | | Invalid NDMREC | 26 | 
I | | Insufficient resource | 28 | 
| | | Request for change direction | | 
I | | (RCD) signalled | 2B | 
I | | Transient Data error during | | 
I I I logging | .60 | 


lii (I 
I X»0C» | SELNERR | Data set not found | 29 | 
I | | Destination does not exist | 41 | 
| | | Media not supported ' | 43 j 
j j | Invalid destination name | 44 | 
I | | Transient Data error during | | 
I I I logging I 60 | 


lii i I 
| X»10» | UNEXPIN | Unexpected sense | F1 | 
I | | Unexpected FMH j F2 j 
I | | Unsupported input | F3 | 



Figure 4.4—1. Batch Data Interchange Response Codes 
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Operands of DFHDI Macro 

DEFRESP=YES 

All DFHTC TYPE=WRITE macros issued as a result of the current 
invocation of DFHDI will request a definite response from the 
outboard batch program, irrespective of the specification of 
message integrity for the CICS/VS task. 

DNADDR= 

specifies the name of an outboard destination. If a 
destination with a different name is currently selected, it is 
de— selected before this one is selected. If the current 
destination is being re-specified then no selection is 
performed. This operand cannot be used with the SELECT 
operand . 

symbolic— address 

is the address of a field defining the destination name. 
This field consists of a one byte name length followed by 
the name itself. 

YES 

indicates that the application program has set this address 
into the word field TCADIDNA. The current implementation 
gives a maximum length of 8 characters for the destination 
name. 

DSSTAT=symbolic address 

specifies the entry label of the user-written routine to which 
control is passed when testing of the return code indicates a 
discontinuity in the inbound data stream. Return codes are 
described earlier in this chapter. 

EODS=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed when testing of the response code indicates 
the end of the data stream. Return codes are described earlier 
in this chapter. 

FUNCERR=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed when testing of the return code indicates a 
function error. Return codes are described earlier in this 
chapter. 

KEIADDR= 

This identifies a record of a keyed direct data set. 

symbolic address 

specifies the address of a field defining the primary key 
of the record in a keyed direct data set to be erased. 
This field consists of a one byte key length followed by 
the key itself. 
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YES 

indicates that the application has set this address into 
fullword TCADIKYA. The current implementation gives a 
maximum length of 24 characters for the record key. 

Note ; This operand is not required when adding records to a 
3790 keyed direct data set as the key value is embedded in the 
data specified by the DATA operand. 

See 3790 Host System Programmer 1 s Guide for a specification of 
valid keys. 



NUMREC= 



specifies the number of records affected by the current 
request. The 3790 will accept values greater than 1 only for 
the REPLACE operation on an addressed direct data set. The 
value is not meaningful to CICS/VS but is conveyed to the 
outboard batch program as part of the function selection 
information. Records are replaced sequentially starting with 
the one identified by the RRNADDR operand. 

integer 

specifies the number of records, in the range 1 thru 255, 
that are to be replaced. 



YES 



specifies that the application has set the binary value 
into the one byte field TCADINRS. If omitted this operand 
defaults to the value 1. 



NORESP=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed when testing of the return code indicates 
normal response, that is, no errors have occurred during the 
processing specified by a DFHDI macro. Return codes are 
described earlier in this chapter. 



RRNADDR= 



SELECT= 



identifies a record of an addressed direct data set for the 
function REPLACE. 

record— id 

is the address of a one word field containing the relative 
record number of the record being replaced. 



YES 



indicates that the application has set this address into 
the fullword TCADIRNA. 



Note ; Record identifiers begin with the value 1. 



specifies the type of output medium for the function SEND. 
This operand cannot be used with the DNADDR operand. 

CONSOLE 

specifies the medium provided for messages to the operator 

PRINT 

specifies a printer. 
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CARD 

specifies a card reader/punch. 

WPMEDIA1 through WPMEDIA4 

specify, respectively, word processing media 1, 2, 3 and 4. 



nn 



TES 



specifies a medium sub— address in the range 00 to 15, where 
15 means any available subaddress. The default is 00. 



specifies the medium code and sub-address have been placed 
in the one— byte field TCADISEL by the application program. 

The first half of this field must contain a hexadecimal 
code indicating the type of medium, as shown below. The 
second half must contain the hexadecimal value of the sub- 
address (X^OO 1 through X»15«) . 



Code Meaning 



x»oo» 


CONSOLE 


X«20« 


CARD 


X»30« 


PRINT 


X»80« 


WPMEDIA1 


X»90« 


WPMEDIA2 


X»A0» 


WPMEDIA3 


X^O* 


WPMEDIA4 



SELNERR=symbolic address 

specifies the entry label of the user— written routine to which 
control is passed when testing of the return code indicates 
errors during destination selection. Return codes are 
described earlier in this chapter. 

ONEXPIN=symbolic address 

specifies the entry label of the user-written routine to which 
control is passed when testing of the return code indicates 
that unexpected or unrecognizable input or response is received 
in reply to a DFHDI macro. Return codes are described earlier 
in this chapter. 



V0LADDR= 



specifies, for the 3770 programmable subsystem only, the name 
of the diskette volume containing the data set named in the 
DNADDR operand. This name is used to qualify the data set name 
for destination selection. Subsequent specifications of the 
same data set name without a diskette volume name, or with a 
different diskette volume name, will cause a new destination to 
be selected. In the former case, all mounted diskette volumes 
will be searched for the data set named in the DNADDR operand. 

symbolic address 

specifies the address of the field defining the diskette 
volume name (to a maximum of six characters) . The field 
consists of a one— byte name length followed by the name 
itself. 



YES 



indicates that the application program has set this address 
into the fullword field TCADIVNA. 
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Chapter 5.1. Introduction to Control Operations 



This part of the manual describes the CICS/VS macro instructions that 
control the execution of tasks within a CICS/VS system- The macros are 
associated with appropriate control programs and the specification of 
the various TYPE= operands invokes a range of operations. 

The control programs and the macro instructions associated with each 
are as follows: 

• Interval Control Program (DPHIC Macro) . This macro specifies 
operations that depend on the time of day and can have nine types 
of operations associated with it: GETIME, WAIT, POST, INITIATE, 
PUT, GET, CANCEL, RETRY, and CHECK. These operations are described 
in Chapter 5.2. 

• Task Control Program (DPHKC Macro) . This macro specifies 
operations that affect task activity or the control of resources. 
It can have eight types of operation associated with it: ATTACH, 
SCHEDULE, CHAP, HAIT, ENQ, DEQ, PURGE, and NOPURGE. These 
operations are described in Chapter 5.3. 

• Program Control Program (DFHPC Macro) . This macro specifies 
operations that affect the flow of control between application 
programs. It can have ten types of operation associated with it: 
LINK, XCTL, LOAD, RETURN, DELETE, ABEND, SETXIT, RESETXIT, COBADDR, 
and CHECK. These operations are described in Chapter 5.4. 

• Storage Control Program (DFHSC Macro) . This macro specifies 
operations that affect the acquisition and release of areas of main 
storage. It can have two types of operation: GETMAIN and FREEMAIN. 
These operations are described in Chapter 5.5. 

• Transient Data Control Program (DFHTD Macro) . This macro specifies 
operations that affect the queuing and retrieval of data in main 
storage or auxiliary storage. It can have five types of operation: 
PUT, GET, FEOV, PURGE, and CHECK. These operations are described 
in Chapter 5.6. 

• Temporary Storage Control Program (DFHTS Macro) . This macro 
specifies operations that affect the temporary storage of data in 
main storage or auxiliary storage. It can have seven types of 
operation: PUT, PUTQ, GET, GETQ, RELEASE, PURGE, and CHECK. These 
operations are described in Chapter 5.7. 
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Chapter 5.2. Interval Control (DFHIC Macro) 



CICS/VS maintains the current time of day in two formats: a binary 
value, in CSACTODB, which is updated automatically during task 
dispatching to reflect the time of day maintained by the operating 
system, and a packed value, in CSATODP, which is updated when control 
returns from an operating system WAIT or when a DFHIC 

TYPE=GETIME,FORM=PACKED macro is executed. The accuracy of these values 
at a given moment depends upon the task mix and the frequency of task 
switching operations. 

Time management provides the capability of controlling various task 
fuD^tions based on the time of day or on intervals of time. The time 
services available are listed below and are available to the application 
programmer through use of the interval control macro instruction 
(DFHIC;. 

1. Provide the time of day in binary or packed decimal representation. 

2. Provide task synchronization based on time-dependent events. 

3. Provide automatic time-ordered task initiation with associated data 
retention and recovery support. 

The application programmer must specify parameter values when using 
the DFHIC macro instruction. The values can be specified in either of 
two ways: 

1. By including the parameters in operands of the DFHIC macro 
instruction by which time services are reguested, or 

2. By coding instructions that place the parameter values in fields of 
the TCA prior to issuing the DFHIC macro instruction. 

The second of these approaches provides flexibility in that the 
parameter values of a single DFHIC macro instruction can be altered at 
execution time. 

The application programmer can check the CICS/VS response to a 
request for time services as explained under "Test Response to a Request 
for Time Services," later in this chapter. If the programmer does not 
check for a particular response, and the condition corresponding to that 
response occurs, program flow proceeds to the next sequential 
instruction in the application program. All operands that can be 
included in the DFHIC macro instruction are discussed in detail at the 
end of the chapter. 
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Time-of-Day Updating (TYPE=GETIME) 

The format of the DPHIC macro instruction to request updating of 
CICS/VS-maintained time— of— day values to the current clock time is as 
follows: 



TYPE=GETIME 

[ , FORM= {BINARY | PACKED} ] 

[ ,TIMADR= {symbolic address| YES} ] 

[ , NORESP=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,ERROR=symbolic address] 



In the course of normal operation, CICS/VS maintains the current time 
of day in binary form at CSACTODB and in packed decimal form at CSATODP. 
The binary representation is expressed as a four— byte positive value in 
hundredths of a second. The packed decimal representation is expressed 
as a four— byte positive signed value of the form HHMMSSt+ where the 
seconds are truncated to tenths of a second. The binary value is 
updated periodically during task dispatching, and the packed decimal 
value is updated when returning from an operating system WAIT. The 
accuracy of these values at any given moment depends on the task mix and 
the frequency of task switching operations. 

The application programmer can ensure that one or both of these time— 
of— day values are updated to a current setting by issuing the DFHIC 
TYPE=GETIME macro instruction. This macro instruction causes one or 
both forms of the time of day to be updated in the CSA and, optionally, 
places the requested form of the time of day in a four— byte field 
specified by the application programmer. When the programmer wants the 
time of day to be returned in a field other than those of the CSA, 
either the symbolic label of the four— byte field must be specified in 
the DFHIC TYPE=GETIME macro instruction or the address of the field must 
be placed in TCAICDA prior to issuing the DFHIC TYPE=GETIME macro 
instruction. 

N ote : For performance reasons, it should be recognized that lengthy 
conversion routines must be executed whenever updating of the packed 
decimal representation of time of day is requested. 

The following example shows how to request that the time of day be 
placed at the storage locations represented by the symbolic label CLOCK. 

DFHIC TYPE=GETIME, REQUEST CURRENT TIME-OF-DAY * 

FORM=PACKED, PACKED DECIMAL FORM * 

TIMADR=CLOCK SYMBOLIC ADDRESS FOR RESPONSE 

The following examples show how to request that the time of day be 
placed in a field selected prior to (and independent of) execution of 
the DFHIC TYPE=GETIME macro instruction. 

For Assembler language : 

MVC TCAICDA, =A (CLOCK) MOVE ADDR FOR RESPONSE TO TCA 
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DFHIC TYPE=GETIME, 
FORM=PACKED, 
TIMADR=YES 



REQUEST CURRENT TIME-OF-DAY * 

PACKED DECIMAL FORM * 

RESPONSE ADDRESS GIVEN 



For COBOL : 

MOVE CLOCKADR TO TCAICDA, 



NOTE MOVE ADDR FOR RESP TO TCA . 



DFHIC TYPE=GETIME, 
FORM=PACKED, 
TIMADR=YES 



REQUEST CURRENT TIME-OF-DAY * 
PACKED DECIMAL FORM * 

RESPONSE ADDRESS GIVEN 



Fo r PL/I : 

TCAICDA=ADDR (CLOCK) ; 



/♦MOVE ADDR FOR RESP TO TCA*/ 



DFHIC TYPE=GETIME, 
FORM=PACKED, 
TIMADR=YES 



REQUEST CURRENT TIME-OF-DAY * 
PACKED DECIMAL FORM * 

RESPONSE ADDRESS GIVEN 
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Delay Processing of a Task (TYPE=WAIT) 



The format of the DPHIC macro instruction to delay processing of a task 
until a specified time occurs is as follows: 




TYPE=WAIT 

[ ,INTRVAL={numeric value | IBS} ]|[ ,TIME={numeric 

value|YES} ] 
[ ,REQID={name |YES| ' prefix •} ] 
[ ,N0RE5P=symbolic address] 
[ ,INVREQ=symbolic address] 
[ ,EXPIRD=symbolic address] 
[ ,ERROR=symbolic address] 



The task synchronization feature of CICS/VS time management provides the 
capability either of delaying the processing of a requesting task until 
a specified time occurs or of signaling the requesting task when a 
specified interval of time has elapsed. It also supports the 
cancellation of a pending time-ordered synchronization event by another 
task. (See "Time-Ordered Request Cancellation (CANCEL)," later in this 
chapter.) 

This macro instruction causes the requesting task to temporarily 
suspend processing, and to resume control at a specified time of day or 
after a specified interval of time has elapsed. The INTRVAL and TIME 
operands are mutually exclusive. It supersedes and cancels any 
previously initiated DFHIC TYPE=POST request for the task. 

A numeric value specified in, or before issuing, the DFHIC TYPE=WAIT 
macro instruction is used by CICS/VS to calculate the time at which the 
requested time service is to be provided. If the calculated time of day 
is the same as the current clock time, or up to and including six hours 
preceding the current clock time, the specified time is considered to 
have elapsed (occurred) and the reguested service is provided 
immediately. If the calculated time of day is earlier than the current 
clock time, the requested service is provided when the specified time 
occurs. If the calculated time of day precedes the current clock time 
by more than six hours, the requested service is provided the next day 
at the specified time. 

To identify the request and any data associated with it, a unique 
identification is assigned to each time-ordered request. The 
application programmer can specify a request identification to be 
assigned to his DFHIC TYPE=WAIT macro by the REQID operand. If none is 
assigned by the programmer, CICS/VS assigns a unigue request 
identification. A request identification should be specified by the 
application programmer if he wishes to provide another task with the 
capability of canceling the unexpired WAIT request. (See the section 
"Time— ordered Request Cancellation (CANCEL) ," later in this chapter.) 

The following example shows how to temporarily suspend the processing 
of a task for a specified period of time: 



DFHIC TYPE=WAIT, 

INTRVAL=500, 
REQID=GXLBZQMR 



DELAY TASK PROCESSING, 
WAIT 5 MINUTES SECONDS 
UNIQUE REQUEST ID 
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The following examples show how to request the suspension of a task 
until the time of day stored previously in TCAICRT is reached. A 
reguest identification previously selected by the user is stored in 
TCAICQID as a unique identifier for this request for time service. 



F or Assembler lang u age : 



MVC TCAICRT, =PL4» 124500* 
MVC TCAICQID, UNIQCODE 



MOVE 12:45 TO TCA 
UNIQUE REQUEST ID TO TCA 



DPHIC TYPE=HAIT, 
TIME=YES, 
REQID=YES 



DELAY TASK PROCESSING 
EXPIRATION TIME GIVEN 
UNIQUE ID GIVEN 



For COBOL: 



MOVE 124500 TO TCAICRT. 
MOVE UNIQCODE TO TCAICQID 



NOTE MOVE 12:45 TO TCA. 

NOTE UNIQUE REQUEST ID TO TCA 



DFHIC TYPE=WAIT, 
TIME=YES, 
REQID=YES 



DELAY TASK PROCESSING 
EXPIRATION TIME GIVEN 
UNIQUE ID GIVEN 



For PL/I: 



TCAICRT=124500; 
TCA ICQID=UNIQCODE; 



/*MOVE 12:45 TO TCA*/ 
/♦UNIQUE REQUEST ID TO TCA*/ 



DFHIC TYPE=WAIT, 
TIME=YES, 
REQID=YES 



DELAY TASK PROCESSING 
EXPIRATION TIME GIVEN 
UNIQUE ID GIVEN 
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Signal Expiration of a Specified Time (TYPE = POST) 

The format of the DFHIC macro instruction to request that CICS/VS signal 
when a specified time has expired is as follows: 



1 


DFHIC 


r - -™ ■-"' ■' - - -- -- ' ~ ■ i 

TYPE=POST | 
[ ,INTRVAL= {numeric value |TES} ]|[ ,TIME = {numeric | 
value|YES} ] I 
[ ,REQID= {name | YES | 'prefix 1 } ] | 
[ ,NORESP=symbolic address] | 
[ ,INVREQ=symbolic address] | 
[ ,EXPIRD=symbolic address] | 
[ ,ERROR=symbolic address] | 



In response to this macro instruction, CICS/VS makes a timer event 
control area available to the user for testing. This four-byte storage 
area is initialized to binary zeros and its address is returned to the 
requesting task in TCAICTEC. 

When CICS/VS determines that the time specified in a DFHIC TYPE=POST 
macro instruction has expired, byte of the timer event control area is 
set to X^UO 1 and byte 2 is set to X a 80 B . This form of posting is 
compatible with the completion code postings performed by the operating 
systems. The timer event control area can be used as the event control 
area referred to in a DFHKC TYPE=WAIT macro instruction. (See the 
discussion of task synchronization in Chapter 5.3.) 

The timer event control area provided to the user is not released or 
altered (except as described above) until one of the following events 
occurs: 

• The task issues a subsequent DFHIC TYPE=WAIT, DFHIC TYPE=POST, 
DFHIC TYPE=INITIATE, or DFHIC TYPE=PUT macro. 

• The task issues a DFHIC TYPE=CANCEL macro request to nullify the 
DFHIC TYPE=POST macro (this releases the storage area occupied by 
the timer event control area) . 

• The task terminates, normally or abnormally. 

A task can have only one DFHIC TYPE=POST request active at any given 
time. Any DFHIC TYPE=WAIT, DFHIC TYPE=POST, DFHIC TYPE=INITIATE, or 
DFHIC TYPE=PUT request supersedes and cancels a previously issued DFHIC 
TYPE=POST request by the task. 

Note : The expiration of any CICS/VS time-ordered event is determined by 
CICS/VS when it is performing its task dispatching function. Therefore, 
for "posting" to occur, the application programmer must ensure that the 
task relinquishes control of CICS/VS before each testing of the timer 
event control area. This can be done directly by issuing the DFHKC 
TYPE=WAIT or DFHKC TYPE=CHAP macro instruction (see the discussion of 
task synchronization in Chapter 5.3.) or indirectly by requesting a 
CICS/VS service that in turn initiates a task service on behalf of the 
task. 

A numeric value specified in, or before issuing, the DFHIC TYPE=POST 
macro instruction is used by CICS/VS to calculate the time at which the 
requested time service is to be provided. If the calculated time of day 
is the same as the current clock time, or up to and including six hours 
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preceding the currant clock time, the specified time is considered to 
have elapsed (occurred) and the requested service is provided 
immediately. If the calculated time of day is in advance of the current 
clock time, the requested service is provided when the specified time 
occurs. If the calculated time of day precedes the current clock time 
by more than six hours, the requested service is provided the next day 
at the specified time. 

The application proqrammer can specify a request identification to be 
assigned to a posting request by the REQID operand. If none is assigned 
by the programmer, CICS/VS assigns a unique request identification, 
which is returned to the application program in TCAICQID. In either 
case, the request identification provides a means of symbolically 
identifying the request. This macro indicates that CICS/VS is to make a 
four— byte timer event control area available to the application program 
for testing. The area is initialized to binary zeros, and its address 
is returned in TCAICTEC to the application program. This area is 
available to the application program for the duration of the task and is 
overridden if the application program issues another DFHIC request of 
the following types: POST, WAIT, POT, or INITIATE. 

The following example shows how to request that CICS/VS provide a 
signal for the task when a specified interval of time has elapsed: 



DFHIC TYPE=POST, 
INTRVAL=30 



SIGNAL WHEN INTERVAL PASSES 
INTERVAL IS 30 SECONDS 



The following examples show how to dynamically request that CICS/VS 
provide a signal for the task when the time of day previously stored in 
TCAICRT is reached. Since no request identification is specified by the 
application programmer, CICS/VS automatically assigns one and returns it 
to the application program at TCAICQID. 



For Assembler language : 

HVC TCAICRT, PACKTIME 



STORE CALCULATED EXPIR TIME 



DFHIC TYPE=P0ST, 

TIHE=YES 
MVC UNIQCODE, TCAICQID 



SIGNAL WHEN TIME OCCORS 

EXPIRATION TIME GIVEN 

SAVE CICS/VS UNIQUE REQUEST ID 



For COBOL : 

MOVE PACKTIME TO TCAICRT, 



NOTE STORE CALC EXPIR TIME. 



DFHIC TYPE=P0ST, 

TIHE=YES 
MOVE TCAICQID TO UNIQCODE 



SIGNAL WHEN TIME OCCURS 

EXPIRATION TIME GIVEN 

NOTE SAVE UNIQUE REQUEST ID, 



For PL/I : 

TCAICRT=PACKTIME; 



/♦STORE CALCULATED EXPIR TIME*/ 



DFHIC TYPE=POST, 

TIME=YES 
UNIQCODE=TCAICQID ; 



SIGNAL WHEN TIME OCCURS 
EXPIRATION TIME GIVEN 
/♦SAVE UNIQUE REQUEST ID*/ 
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Initiate a Task without Data (TYPE = INITIATE) 



The format of the DFHIC macro instruction to request that CICS/VS 
initiate a task at some future time is as follows: 




TYPE=INITIATE 

[ , I NTRVAL= {numeric value | YES} ]|[ ,TIME= {numeric 

value | YES} ] 
[ # REQID={name|YES| 'prefix'} ] 
[ ,TRANSID=name] 
[ ,TRMIDNT={name|YES} ] 
[ ,NORESP=symbolic address] 
[ / INVREQ=symbolic address] 
[ ,TRNIDER=symbolic address] 
[ ,TRMIDER=symbolic address] 
[ ,ERROR=symbolic address] 



Through this macro instruction, the application programmer provides 
the transaction identification of the task to be initiated at some 
future time and other information pertaining to the task. CICS/VS 
queues the request until the specified time occurs. When the necessary 
resources are available (for example, a terminal) , the task is 
initiated. Only one task is initiated if multiple DFHIC TYPE=INITIATE 
requests for the same transaction and terminal expire at the same time 
or prior to terminal availability. No data can be passed to the future 
task by means of the DFHIC TYPE=INITIATE macro instruction. (To do so, 
see "Task Initiation with Data (PUT)," which follows.) This request 
supersedes and cancels any previously initiated DFHIC TYPE=POST request 
by the initiating task. 

A numeric value specified in or before issuing the DFHIC 
TYPE=INITIATE macro instruction is used by CICS/VS to calculate the time 
of day at which the requested time service is to be provided. If the 
calculated time of day is the same as the current clock time, or up to 
and including six hours preceding the current clock time, the specified 
time is considered to have elapsed (occurred) and the requested service 
is provided immediately. If the calculated time of day is in advance of 
the current clock time, the requested service is provided when the 
specified time occurs. If the calculated time of day precedes the 
current clock time by more than six hours, the requested service is 
provided the next day at the specified time. 

As stated earlier, a unique request identification is assigned to 
each time— ordered request as a means of symbolically identifying the 
request and any data associated with it. The application programmer can 
specify an identifier for his initiation request, or he can let CICS/VS 
assign one, in which case it is returned to the application program in 
TCAICQID. 

The application programmer must specify the transaction 
identification of the future task, either in the DFHIC TYPE=INITIATE 
macro instruction or by placing it in TCAICTI before issuing the macro 
instruction. CICS/VS validates the transaction identification by 
scanning the program control table (PCT) . If the specified identifier 
is not found in the table, CICS/VS does not provide the requested 
service; a response code is placed at TCAICTR (for Assembler language or 
PL/I) or at TCAICRC (for COBOL) to indicate that the transaction 
identification is not valid. 
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If the future task must communicate with a terminal, the application 
programmer must also specify a terminal identification, either in the 
macro instruction or by placing it beforehand in TCAICTID. CICS/VS 
validates the terminal identification by scanning the terminal control 
table (TCT) ; if it fails to locate the terminal identification in the 
TCT, CICS/VS provides a response code at TCAICTR (for assembler language 
or PL/I) or at TCAICRC (for COBOL) without servicing the reguest. 

The following example shows how to request automatic initiation of a 
specified task not associated with a terminal: 



DPHIC TYPE=INITIATE, 
INTRVAL=10000, 
TRANSID=TRNL 



REQUEST TASK INITIATION * 

IN ONE HOUR * 

TRANSACTION IDENTIFICATION 



The following examples show how to dynamically request automatic 
initiation of a task associated with a terminal. The task initiation 
time, transaction identification, and terminal identification are moved 
to fields of the TCA before the DPHIC TYPE=INITIATE macro instruction is 
issued. Since no request identification is specified by the application 
programmer, CICS/VS automatically assigns one and returns it to the 
application program at TCAICQID. 



For Assembler language : 

MVC TCAICRT,=PL4» 10000*, 
MVC TCAICTI,=CL4 , TRN1» 
MVC TCAICTID,=CL4»STA5» 



MOVE ONE HOUR TO TCA 
TRANSACTION ID TO TCA 
TERMINAL ID TO TCA 



DFHIC TYPE=INITIATE, 
INTRVAL=YES, 
TRMIDNT=YES 

MVC UNIQCODE, TCAICQID 



REQUEST TASK INITIATION 
INTERVAL OF TIME GIVEN 
TERMINAL ID GIVEN 
SAVE CICS/VS UNIQUE REQUEST ID 



For COBOL: 



MOVE 10000 TO TCAICRT. 
MOVE »TRN1» TO TCAICTI. 
MOVE *STA5* TO TCAICTID, 



NOTE MOVE ONE HOUR TO TCA. 
NOTE TRANSACTION ID TO TCA. 
NOTE TERMINAL ID TO TCA. 



DFHIC TYPE=INITIATE, 

INTRVAL=YES, 

TRMIDNT=YES 
MOVE TCAICQID TO UNIQCODE 



REQUEST TASK INITIATION 
INTERVAL OF TIME GIVEN 
TERMINAL ID GIVEN 
NOTE SAVE UNIQUE REQUEST ID 



For PL/I: 



TCAICRT=10000; 

TCAICTI=*TRN1*; 

TCAICTID=»STA5»; 



/♦MOVE ONE HOUR TO TCA*/ 
/♦TRANSACTION ID TO TCA*/ 
/♦TERMINAL ID TO TCA*/ 



DFHIC TYPE=INITIATE, 
INTRVAL=YES, 
TRMIDNT=YES 

UNIQCODE=TCAICQID; 



REQUEST TASK INITIATION 
INTERVAL OF TIME GIVEN 
TERMINAL ID GIVEN 
/*SAVE UNIQUE REQUEST ID*/ 
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Task Initiation with Data (TYPE=PUT) 



The format of the DFHIC macro instruction to request automatic task 
initiation and/or request that data be made available to a task is as 
follows: 




TYPE=PUT 

[ ,INTRVAL= {numeric value | IES} ] | [ ,TIME= {numeric 

value | YES} ] 
[ ,REQID={name| YES| •prefix 1 } ] 
[ ,TRANSID=name] 
[ ,TRMIDNT={name|YES} ] 
[ ,ICDADDR= {symbolic address|YES} ] 
[ ,NORESP=symbolic address] 
[ , INVREQ=symbolic address] 
[ ,TRNIDER=symbolic address ] 
[ , TRMIDER=symbolic address] 
[ ,IOERROR=symbolic address] 
[ f ERROR=symbolic address] 



This macro indicates that CICS/VS is to initiate a nonterminal- 
oriented task at some future time and makes one data record available to 
that task, or provides time-ordered data to be made available to a 
terminal— oriented task that is to be initiated at some future time. 

This macro instruction is used to provide the transaction 
identification, the location of the data to be stored, and other 
information applicable to the task to be initiated. CICS/VS stores the 
data and queues the request until the specified time occurs. As soon as 
all necessary resources are available (for example, a terminal) , the 
task is initiated. CICS/VS temporary storaqe manaqement facilities 
support this facility of time manaqement. 

The DFHIC TYPE=PUT macro instruction is used only when data is to be 
passed to a task to be initiated at some future time. It supersedes and 
cancels any previously initiated DFHIC TYPE=POST request of the task. 
If only task initiation at a future time is needed, the DFHIC 
TYPE=INITIATE macro instruction should be used. 

If the task to be initiated is associated with a terminal, the 
initial DFHIC TYPE=PUT request causes the task to be initiated at the 
specified time. Subsequent PUTs with the same terminal identification e 
transaction identification, and expiration time are used to store data 
for subsequent retrieval by the initiated task. If the task to be 
initiated is not associated with a terminal, each DFHIC TYPE=PUT request 
results in a task beinq initiated at the specified time. That is, only 
one physical data record can be passed to a task not associated with a 
terminal. (See the section "Retrieve Time-Ordered Data (GET) ," which 
follows.) 

Most operands of the DFHIC TYPE=PUT macro instruction are analoqous 
to similar operands of the DFHIC TYPE=INITIATE macro instruction. The 
discussions of time calculation, request identification, transaction 
identification, and terminal identification qiven in the section "Task 
initiation without Data (INITIATE ),»• which precedes this section, apply 
to DFHIC TYPE=PUT in the same manner as they apply to DFHIC 
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TYPE=INITIATE. In addition, because the DPHIC TYPE=PUT macro 
instruction permits data to be passed, the application programmer must 
specify the symbolic address of the field containing the data. The 
label may be provided as a parameter of the macro instruction or move 
the address to TCAICDA prior to issuing the macro instruction. 

The data passed to an initiated task must have the standard variable- 
length format, with the first four bytes containing LLJtfJrf. LL is a two- 
byte binary length field (the value of which includes the length of the 
data plus the first four bytes) , and )6)5 is a two— byte field containing 
binary zeros. 

Note ; An IOERROR will occur if there is not enough auxiliary temporary 
storage available to hold the data being passed. See the CICS/VS System 
Programmer's Reference Manual discussion of temporary storage for 
further details of auxiliary temporary storage reguirements. 

The following example shows how to reguest automatic task initiation 
and/or reguest that time— ordered data be made available to a task 
associated with a terminal: 



DFHIC TYPE=PUT, 

TIME=173000, 
TRANS ID=TRH2, 
TRMIDNT=STA3, 
ICDADDR=DATAFLD 



REQUEST TASK INITIATION * 

TIME IS 5:30 PM * 

TRANSACTION IDENTIFICATION * 

TERMINAL IDENTIFICATION * 
DATA ADDRESS 



The following examples show how to dynamically reguest automatic task 
initiation and/or reguest that time— ordered data be made available to a 
task associated with a terminal. Values for time, reguest 
identification, transaction identification, and terminal identification, 
as well as the address of data to be passed, are moved to appropriate 
fields of the TCA before issuing the DFHIC TYPE=PUT macro instruction. 



F or Assembler language : 



HVC TCAICRT,PACKTIHE 
MVC TCAICQID,UNIQCODE 
MVC TCAICTI,=CL4»TRN2" 
MVC TCAICTID,=CL4 , STA3» 
MVC TCAICDA, =A pATAFLD) 



CALCULATED EXPIR TIME TO TCA 
UNIQUE REQUEST ID TO TCA 
TRANSACTION ID TO TCA 
TERMINAL ID TO TCA 
ADDRESS OF DATA TO TCA 



DFHIC TYPE=PUT, 
TIME=YBS, 
TRMIDNT=YES, 
REQID=YES, 
ICDADDR=YES 



REQUEST TASK INITIATION 
EXPIRATION TIME GIVEN 
TERMINAL ID GIVEN 
UNIQUE REQUEST ID GIVEN 
DATA ADDRESS GIVEN 
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For COBOL: 



MOVE PACKTIME TO TCAICRT. 
MOVE ONIQCODE TO TCAICQID 
MOVE »TRN2» TO TCAICTI. 
MOVE »STA3' TO TCAICTID. 
MOVE DATADDR TO TCAICDA. 



NOTE CALC EXPIR TIME TO TCA . 
NOTE UNIQUE REQUEST ID TO TCA, 
NOTE TRANSACTION ID TO TCA. 
NOTE TERMINAL ID TO TCA. 
NOTE ADDRESS OP DATA TO TCA. 



DFHIC TYPE=PUT, 
TIMB=YES, 
TRMIDNT=YES, 
REQID=YES, 
ICDADDR=YES 



REQUEST TASK INITIATION 
EXPIRATION TIME GIVEN 
TERMINAL ID GIVEN 
UNIQUE REQUEST ID GIVEN 
DATA ADDRESS GIVEN 



For PL/I; 



TCAICRT=PACKTIME; 
TC AICQID=0NIQCODE ; 
TCAKT^'TR^*; 
TCAICTID= , STA3 I ; 
TCAICDA=ADDR (DATAFLD) ; 



/♦CALC EXPIR TIME TO TCA*/ 
/*UNIQUE REQUEST ID TO TCA*/ 
/TRANSACTION ID TO TCA*/ 
/♦TERMINAL ID TO TCA*/ 
/*ADDRESS OF DATA TO TCA*/ 



DFHIC TYPE=PUT, 
TIME=YES, 
TRMIDHT=YES, 
REQID=YES, 
ICDADDR=YES 



REQUEST TASK INITIATION 
EXPIRATION TIME GIVEN 
TERMINAL ID GIVEN 
UNIQUE REQUEST ID GIVEN 
DATA ADDRESS GIVEN 
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Retrieve Time-Ordered Data (TYPE=GET) 



The format of the DFHIC macro instruction to retrieve data stored by a 
DFHIC TYPE=POT macro instruction (issued by another task) is as follows: 



1 1 1 -,._-.. -. , _ _ . — -- _. 

I | DFHIC | TYPE=GET 


, — , 


I 1 | [ ,ICDADDR= {symbolic address| YES} ] 




| | | [ ,RELBASE=NO] 




I | 1 [ ,NORESP=symbolic address] 




I | | [ ,INVREQ=symbolic address] 




| | | [ ,NOTFND=symbolic address] 




| | | [ ,ENDDATA=symbolic address] 




I | | [ , IOERROR=symbolic address] 




I | | [ ,TSINVLD=symbolic address] 




| | | [ ,ERROR=symbolic address] 





Only data from an expired DFHIC TYPE=PUT request can be accessed 
using the DFHIC TYPE=GET macro instruction. To retrieve data stored by 
use of a DFHIC TYPE=PUT request, the DFHIC TYPE=GET macro instruction 
must be used. 



When time— ordered data is to be retrieved by mea 
TYPE=GET macro instruction, the application program 
address of a storage area into which the data is to 
address is specified either by including the addres 
instruction or by storing it in TCAICDA prior to is 
instruction. In either case, the storage area must 
contain the four-byte length field (LL)#Q at the be 
record as well as the data portion of the record, 
programmer does not select a storage area, CICS/VS 
acguires an area of sufficient size and returns the 
in TCAICDA. 



ns of a DFHIC 

mer may specify the 

be placed. The 
s in the macro 
suing the macro 

be large enough to 
ginning of the data 
If the application 
automatically 

address of that area 



Each originating DFHIC TYPE=PUT request provides the transaction 
identification of the task to receive the data, and if applicable, 
symbolically identifies the terminal associated with the task's 
operation. When CICS/VS services a DFHIC TYPE=PUT request, it does so 
in two steps; it first queues the request for automatic task initiation 
at a specified time and then stores the data. When the specified time 
occurs, the task is ready to be initiated, and the stored data is then 
available for retrieval. 

A task not associated with a terminal that is initiated as a result 
of an expired DFHIC TYPE=PHT request can access only the single physical 
data record associated with the original request. It does this by 
issuing one DFHIC TYPE=GET macro instruction. The storage occupied by 
the data associated with the task is released upon execution of the 
DFHIC TYPE=GET request, or upon termination of the task (normally or 
abnormally) if no DFHIC TYPE=GET macro instruction is executed prior to 
termination. 

A task associated with a terminal that is initiated as the result of 
an expired DFHIC TYPE=POT request, or that is active at the time of 
expiration of a DFHIC TYPE=POT request, can access all data records 
associated with expired DFHIC TYPE=POT macro requests having the same 
transaction identification and terminal identification. Therefore, a 
task associated with a terminal can retrieve all data made available to 
the terminal and the task up to the current time by issuing consecutive 
DFHIC TYPE=GET requests. Expired data records are presented to the task 
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upon request in expiration time sequence. The storage occupied by the 
single data record associated with a DFHIC TYPE=PUT request is released 
after the data has been retrieved by a DFHIC TYPE=GET request or upon 
termination of CICS/VS. Data passed in subsequent expired DFHIC 
TYPE=PUT requests specifying the same terminal identification and 
transaction identification can be retrieved in response to DFHIC 
TYPE=GET requests by the same task if that task is still active at their 
expiration times. Otherwise, such a DFHIC TYPE=PUT request causes a new 
task to be initiated. 

When all passed data for which specified times have expired has been 
retrieved, CICS/VS provides an end-of-data response at TCAICTR (for 
Assembler language or PL/I) or TCAICRC (for COBOL) in response to a 
DFHIC TYPE=GET macro instruction. 

The following example shows how to request retrieval of a time- 
ordered data record into a data area specified in the request: 



DFHIC TYPE=GET, 

ICDADDR=DATAFLD 



RETRIEVE TIME-ORDERED DATA 
USER-PROVIDED DATA AREA 



The following examples show how to dynamically request retrieval of a 
time-ordered data record. The address of the storage area reserved for 
the data record is placed in TCAICDA prior to the issuance of the DFHIC 
TYPE=GET macro instruction. 



For Assembler language : 

MVC TCAICDA, =A (DAT AFLD) 



DATA FIELD ADDR TO TCA 



DFHIC TYPE=GET, 

ICDADDR=YES 



RETRIEVE TIME-ORDERED DATA 
DATA FIELD ADDRESS GIVEN 



For COBOL : 

MOVE DATADDR TO TCAICDA 



NOTE DATA FIELD ADDR TO TCA. 



DFHIC TYPE=GET, 

ICDADDR=YES 



RETRIEVE TIME-ORDERED DATA 



For PL/I : 

TCAICDA=ADDR (DATAFLD) ; 



/♦DATA FIELD ADDR TO TCA*/ 



DFHIC TYPE=GET, 

ICDADDR=YES 



RETRIEVE TIME-ORDERED DATA 
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Cancel a Request for Time Services (TYPE=CANCEL) 

The format of the DFHIC macro instruction to cancel a DFHIC TYPE=WAIT, 
DFHIC TYPE=POST, DFHIC TYPE=INITIATE , or DFHIC TYPE=PUT request is as 
follows: 




TYPE=CANCEL 
[ / REQID={name|YES} ] 
[ ,NORESP=symbolic address] 
[ # INVREQ=symbolic address] 
[ , NOTFND=symbolic address] 
[ ,ERROR=symbolic address] 



This macro specifies that a request of one of the following types is 
to be acted upon as follows: 

1. DFHIC TYPE=WAIT issued by another task (now suspended) is to be 
treated as though expired. 

2. DFHIC TYPE=POST issued by this task is to be removed from the 
system. 

3. DFHIC TYPE=POST issued by another task is to be treated as though 
expired. 

4. DFHIC TYPE=INITIATE is to be removed from the system. 

5. DFHIC TYPE=PUT is to be removed from the system. 

The effect of the cancellation is dependent on whether a request 
identification is specified for the DFHIC TYPE=CANCEL request and on the 
type of service request being canceled. 



C ancel an Interval Control POST Request 

A DFHIC TYPE=POST request can be canceled by the originating task or by 
another task through use of the DFHIC TYPE=CANCEL macro instruction. 

When the originating task cancels a DFHIC TYPE=POST request, no 
request identification should be specified for the cancellation request. 
This cancellation request can be made either before or after expiration 
of the original request. In either case, the storage reserved for the 
timer event control area is released, and all references to the original 
request are removed from the system. 

When a task other than the originating task cancels a DFHIC TYPE=POST 
request, the request identification of that request must be specified. 
The effect of the cancellation is the same as an early expiration of the 
original DFHIC TYPE=POST request. That is, the timer event control area 
for the originating task is posted as though the original expiration 
time had been reached. 
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C ancel an Interval Control WAIT Request 

A DFHIC TYPE=WAIT request can only be canceled prior to its expiration, 
and only by a task other than the task that issued the DFHIC TYPE=WAIT 
(the originating task is suspended for the duration of the request) . 
The request identification of the suspended task must be specified. The 
effect of the cancellation is the same as an early expiration of the 
original DFHIC TYPE=WAIT or DFHKC TYPE=CHAP request. That is, the 
originating task resumes control (based on its normal dispatching 
priority) as though the original expiration time had been reached. 



C ancel an Interval Control INITIATE or PUT Request 

A reguest identification must be specified when the DFHIC TYPE=CANCEL 
macro instruction is used to cancel a DFHIC TYPE=INITIATE or DFHIC 
TYPE=PUT request. The effect of the cancellation is to remove the 
original request from the system, treating the original request as 
though it had never been made. The cancellation reguest is effective 
only prior to expiration of the original request. 
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I/O Error Retry (TYPE=RETRY) 



The format of the DPHIC macro instruction to retry an operation 
requested by a DFHIC TYPE=G3T macro instruction when an I/O error occurs 
is as follows: 




TYPE=RETBT 

[ ,RELEASE=NO] 

[ ,NORESP=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,NOTFND=symbolic address] 

[ ,IOERROR=symbolic address] 

[ ,ERROR=symbolic address] 



CICS/VS attempts to retrieve the data record whose symbolic eight- 
character identification is specified at TC&ICQID, and place it into the 
data area specified at TCAICDA. These fields are preset by CICS/VS at 
the time the I/O error response was returned to the application program. 
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Test Response to a Request for Time Services (TYPE= CHECK) 

The format of the DFHIC macro instruction to test the CICS/VS response 
to a reguest for time services is as follows: 




TYPE=CHECK 

[ ,NORESP=symbolic address] 
[ ,INVREQ=symbolic address] 
[ ,EXPIRD=symbolic address] 
[ ,TRNIDER=symbolic address] 
[ ,TRMIDER=symbolic address] 
[ ,NOTFND=symbolic address] 
[ , ENDDATA=symbolic address] 
[ ,IOERROR=symbolic address] 
[ ,TSINVLD=symbolic address] 
[ ,ERROR=symbolic address] 



I Interval Control Response Codes 



The Assembler —language or PL/I programmer can access interval control 
response codes at TCAICTR; the COBOL programmer can access interval 
control response codes at TCAICRC^ The possible response codes and the 
conditions to which they correspond are identified in the right— hand 
columns of Figure 5.2—1. DFHIC macro instructions for which the 
conditions are applicable are shown at the left. 
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Time Services 
Request by 
DFHIC Macro 
Instruction 



Condition 



Response Code 



Assembler | COBOL 



I PL/I 



ALL 



GET, CHECK 



PUT, GET, RETRY, 
CHECK 



INITIATE, PUT, 
CHECK 



INITIATE, PUT, 
CHECK 



GET, CHECK 



WAIT, POST, CHECK 



GET, CANCEL, 
RETRY, CHECK 

ALL 



ALL 



NORESP 
(Normal response) 

ENDDATA 
(End of data con- 
dition) 

IOERROR 
(INPUT/Output 
error) 

TRNIDER 
(Transaction 
identification 
error) 

TRMIDER 
(Terminal ident- 
ification error) 

TSINVLD 
(No temporary 
storage support) 

EXPIRD 
(Expired) 

NOTFND 
(Not found) 

INVREQ 
(Invalid request) 

ERROR 
(Any response 
other than 
NORESP) 



X'OO 



X«01« 



X'04 1 



XM1 1 



XM2' 



X'14' 



X»20» 



X«81» 



X'FF' 



(Note 2) 



LOW-VALUES 
(ICNORESP) 

12-1-9 
(ICENDDATA) 



12-4-9 
(ICIOERROR) 



11-1-9 

(ICTRNIDER) 



11-2-9 

(ICTRMIDER) 

11-4-9 
(ICTSINVLD) 



1 1_0_1-8-9 
(ICEXPIRD) 

12-0-1 

(ICNOTFND) 

12-11-0-7-8-9 

(ICINVREQ) 



(Note 2) 



00000000 
00000001 

00000100 

00010001 

00010010 

00010100 

00100000 
10000001 

11111111 

(Note 2) 



Notes : 

1. The names enclosed in parentheses in the COBOL column indicate 
the condition names generated by CICS/VS. These names may be used 
in testing for the conditions in a COBOL program. 

2. The test for the ERROR response is satisfied by a not equal 
condition; that is, not X'OO', not LOW-VALUES, or not 00000000 
for Assembler, COBOL, and PL/I, respectively. 



Figure 5.2—1. Interval Control Response Codes 

If the application programmer does not check for a particular 
response to his service request, and the exception condition 
corresponding to that response occurs, program flow proceeds to the next 
sequential instruction in the application program. 

The following examples show how to examine the response code provided 
by CICS/VS at TCAICTR (for Assembler language or PL/I) or TCAICRC (for 
COBOL) and transfer control to the appropriate user— written exception- 
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handling routine* The alternative approach available to COBOL 
programmers is also shown. 



For Assembler languag e; 





DFHIC 


TYPE=GET, 
ICDADDR=DATAFLD 




CLI 


TCAICTR,X»00» 




BE 


GOOD 




DFHPC 


TYPE=ABEND , ABCODE=TIME 


GOOD 


DS 


OH 



NORMAL RESPONSE 



For COBOL ; 

DFHIC 

IF 

THEN 
ELSE 
DFHPC 
GOOD. 



TYPE=GET, 

ICDADDR=DATAFLD 
TCAICRC = LOW-VALUES 
GO TO GOOD 
NEXT SENTENCE. NOTE LOW-VALUES NORESP, 

TYPE=ABEND 



Alternatively, the COBOL programmer may make use of the CICS/VS 
generated condition names to test responses. For example: 



IF ICNORESP THEN GO TO GOOD. 



For PL/I: 



DFHIC TYPE=GET, 

ICDADDR=DATAFLD 
IF TCAICTR=»0 , B THEN GO TO GOOD;/*NORMAL RESPONSE*/ 
DFHPC TYPE=ABEND 



GOOD: 
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Operands of DFHIC Macro 

ENDDATA=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if no more data is stored for the task 
issuing a DFHIC TYPE=GET request* It can be considered a 
normal end-of— file response when retrieving sequential time- 
ordered data records. 

ERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if any of the response conditions other 
than NORESP occurs. 

EXPIRD=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the time specified in a DFHIC 
TYPE=POST or DFHIC TYPE=HAIT request has expired at the time 
the reguest is issued. 

FORM = 

indicates which time— of-day representation is desired. 

BINARY 

specifies that a binary representation of time of day (a 
four— byte positive value in hundredths of a second) is to 
be updated and retained in CSACTODB. 

PACKED 

specifies that the binary representation of time of day 
(described above) and the packed decimal representation (a 
four-byte positive value of the form HHMMSSt+ where seconds 
are truncated to tenths of a second) are to be updated and 
retained in CSACTODB and CSATODP respectively. 

Note: COBOL and PL/I programmers should be aware that the 
zone portion of the low— order byte of this positive number 
contains hexadecimal F rather than C or D. 

ICDADDR= 

specifies the location of the data to be stored for the task to 
be initiated at some future time* 

symbolic address 

is the symbolic address of the storage area containing the 
data to be made available to the task. 

YES 

indicates that the symbolic address of the storage area 
containing the data has been placed in TCAICDA. 

If no data is to be passed, DFHIC TYPE=INITIATE rather than 
DFHIC TYPE=PUT should be used. 

INTRVAL= 

specifies the interval of time that is to elapse before CICS/VS 
initiates a task, or before CICS/VS posting is to occur, or for 
which a task is to be suspended* 
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numeric value 

is of the form HHMMSS, where HH represents hours from 00 to 
99, MM represents minutes from 00 to 59, and SS represents 
seconds from 00 to 59. This numeric value is added to the 
current clock time by CICS/VS when the associated macro 
instruction is executed to calculate the time of day (clock 
time) when the task is to be initiated or posted, or when 
processing of the task is to be resumed. When used with 
TYPE=INITIATE, if the specified interval is zero, or if 
both INTRVAL and TIME are omitted, the task is initiated 
immediately. 

YES 

indicates that the interval of time (in packed decimal 
form, HHMMSS+) has been placed in TCAICRT. 

If this operand is specified, the TIME operand cannot be 
specified. 

INVREQ=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an invalid type of request was 
received for processing by the interval control program. 

IOERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an input/output error occurs during 
a DFHIC TYPE=GET or DFHIC TYPE=PUT operation on auxiliary 
storage. The DFHIC TYPE=RETRY macro instruction can be used in 
the routine for handling DFHIC TYPE=GET input/output errors. 

One of the causes of this error is during a TYPE=PUT if there 
is insufficient auxiliary temporary storage available to hold 
any data which is to be passed. See the C ICS/VS System 
Programmer's Guide discussion of temporary storage for further 
details of auxiliary temporary storage requirements. 

NORESP=symoolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if no error occurs. NORESP signifies 
"normal response." 

NOTFND=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the request identification specified 
in a DFHIC TYPE=CANCEL macro instruction fails to match an 
unexpired time— ordered request. It is also applicable to DFHIC 
TYPE=GET or DFHIC TYPE=RETRY requests and signifies that the 
time— ordered data stored for retrieval through the DFHIC 
TYPE=PUT macro instruction cannot be located using the unique 
request identification contained in TCAICQID at the time of 
this request. This condition occurs on a retrieval operation 
if some prior task retrieved the data stored under the request 
identification directly through temporary storage facilities 
and then released the data area. It also occurs if the request 
identification associated with the original DFHIC TYPE=PUT 
request fails to remain a unique identification. 
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RELEiiSE=NO 

indicates that CICS/VS is not to release the record from 
temporary storage after obtaining the record for the 
application program. 

Upon completion of a successful DFHIC TYPE=GET,RELEASE=NO 
request, CICS/VS places the identification of the temporary- 
storage record in TCAICQID. Using this identification, the 
user can retrieve or release the record from temporary storage 
through the DFHTS macro instruction; the record is not 
available to any subsequent DFHIC get requests. 

This operand is valid only for a retry of a DFHIC TYPE=GET 
request. 



REQID= 



TIMADR= 



is an optional operand used to assign a unique request 
identification to this request, as a means of symbolically 
identifying the request. It should be used if the application 
programmer wishes to provide another tasJc with the capability 
of canceling an unexpired WAIT request (see the discussion of 
DFHIC TYPE=CANCEL, later in this chapter) . The data is put in 
temporary storage with this identification. 

name 

is a unique identifier, up to eight characters in length, 
selected for this request by the application programmer. 

YES 

indicates that an eight— character request identification 
has been placed in TCAICQID by the application program. 

•prefix* 

is a two-character (including blanks) prefix to be affixed 
to the Reguest Identification generated by CICS/VS. If 
REQID= ■ • is specified, the prefix is assumed to be in the 
two-byte field TCAICQPX. 

If this operand is omitted, CICS/VS generates a unique request 
identification in the form "DFNNNHNN"; the prefix is DF. 



is used when the time of day is to be returned in an 
application programmer— selected four— byte field. For 
FORM=BINARY, the binary representation is returned; for 
FORM=PACKED, the packed decimal representation is returned. 

symbolic address 

is the symbolic address of the field in which the time of 
day is to be made available to the application program. 

YES 

indicates that the symbolic address of the field for the 
time of day is in TCAICDA. 

If this operand is omitted, the fields of the CSA are updated, 
but the time of day is not placed in another field for 
reference by the application program. 
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TIME= 



specifies the time of day at which CIC5/VS is to initiate the 
requested service. If the specified time of day is the same as 
the current clock time or up to and including six hours 
preceding the current clock time, the specified time is 
considered to have occurred, and the requested service is 
provided immediately. 

numeric value 

is of the form HHMMSS, where HH represents hours from 00 to 
99, MM represents minutes from 00 to 59, and SS represents 
seconds from 00 to 59. 



YES 



indicates that the time of day (in packed decimal form, 
HHMMSS+) has been placed in TCAICRT. 



If this operand is specified, the INTRVAL operand cannot be 
specified . 

TRANSID=name 

is the symbolic transaction identification of the task to be 
initiated. If this operand is omitted, the transaction 
identification is assumed to be in TCAICTI. 

TRMIDER=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the symbolic terminal identification 
specified in the DFHIC TYPE=INITIATE or DFHIC TYPE=PUT request 
cannot be found in the terminal control table (TCT) . 

TRMIDNT= 

is the symbolic terminal identification of the terminal 
associated with the task to be initiated. This operand is 
required when the task to be initiated must communicate with a 
terminal; it saould be omitted otherwise. 

TRNIDER=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the symbolic transaction 
identification specified in a DFHIC TYPE=INITIATE or DFHIC 
TYPE=PUT request cannot be found in the program control taale . 

TSINVLD=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the CICS/VS temporary storage 
program does not support a DFHTS TYPE=GET request issued by the 
CICS/VS interval control program. This situation can occur 
when a dummy temporary storage program is included in the 
current CICS/VS system in place of a functional temporary 
storage program . 
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Task management provides the capability to process transactions (tasks) 
concurrently. Transactions are scheduled,, through task control, and 
processed according to priorities assigned by the user. Control of the 
processor is given to the highest priority task that is ready to be 
processed. Control of the processor is returned to the operating system 
when no further work can be done by CICS/VS or by user— written 
application programs. 

When a transaction is initiated in CICS/VS, task control dynamically 
allocates storage for the task control area (TCA) , places the task on 
the dispatching priority gueue, obtains the program identification of 
the program initially required to process the task from the program 
control table (PCT) , and transfers control to program control. 

The Task Management macro instruction (DFHKC) is used to request any 
of the following services: 

o Initiate a task 

• Change the priority of a task 

• Synchronize a task 

• Synchronize the use of a resource by a task 

o Purge a task on system overload 

The application programmer must specify parameter values when using 
the DFHKC macro instruction. The values can be specified in either of 
two ways: 

1. By including the parameters in operands of the DFHKC macro 
instruction by which task control services are requested, or 

2. By coding instructions that place the parameter values in fields of 
the TCA prior to issuing the DFHKC macro instruction. 

The second method adds flexibility by letting the programmer vary the 
parameter values of a single DFHKC macro instruction to meet the needs 
of a given program . 
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Initiate a Task (TYPE=ATTACH) 

The format of the DFHKC macro instruction to initiate a task is as 
follows: 



I I 

| DFHKC | TYPE=ATTACH 

| | [ ,FCADDR=symbolic address] 

| | [ ,TRANSID=name] 

I I 

i i i i 

This macro instruction causes task control to obtain the task control 
area (TCA) for a task and insert the task in the dispatching priority 
gueue according to the overall transaction processing priority of the 
task. This macro instruction is intended to be used by other CICS/VS 
control modules, but it is also available for use by the application 
programmer to initiate additional tasks* Any additional tasks initiated 
by the application programmer must terminate themselves through use of 
the program control DFHPC TYPE=RETURN macro instruction. 

Most tasks running under CICS/VS are initiated at a terminal and are 
thus associated with a terminal. Tasks initiated by CICS/VS management 
programs (for example, automatic task initiation by transient data 
control) may or may not be associated with a terminal. The contents of 
TCAFCAAA varies depending upon whether the attached task is associated 
with a terminal, a> discussed in the section "Task Control Area (TCA),» 
in Chapter 2.1. 

The number of tasks that can be active within the system at a given 
time is limited by the availability of main storage and/or by the 
"maximum number of tasks" control established by the system programmer 
at system generation or initialization. A new task is not initiated by 
CICS/VS unless sufficient main storage is available to process it. 
Instead, the reguest to initiate a task is gueued (stored) until 
sufficient main storage becomes available. Tasks initiated by CICS/VS 
management modules (for example, terminal control) are subject to the 
maximum number of tasks limitation. Application program reguests for 
attachment of tasks are not subject to this limitation and therefore are 
allowed to exceed the maximum. 

If the DFHKC TYPE=ATTACH macro instruction is used by the application 
programmer, he must provide the facility control area address and 
transaction identification reguired by CICS/VS to initiate a new task. 
The address and identification can be specified in two ways. 

1. By coding two instructions that assign a facility control area 
address to TCAKCFA and a transaction identification to TCAKCTI 
prior to issuing the DFHKC TYPE=ATTACH macro instruction, or 

2. By including the FCADDR=symbolic address operand and 
TRANSID=symbolic name operand in the DFHKC TYPE=ATTACH macro 
instruction, which then stores the assigned values in TCAKCFA and 
TCAKCTI, respectively. 

For all transactions associated with a terminal, the facility control 
area address in TCAKCFA is the address of the TCTTE for the terminal. 
This address provides access to control information necessary for 
communication between the program and the terminal. The first byte is 
an X'OV. If the attaching task owns a terminal, ownership of that 
| terminal (but of no other terminal) may be passed in TCAKCFA. When 
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attaching a task and passing ownership of the terminal to that task, the 
address of the TCA must be stored in TCTTECA. 

If a task is not associated with a terminal, the facility control 
area address can serve as a pointer to additional facility control 
information reguired for execution of the task. For example, it can be 
the address of an entry in the destination control table (DCT) that is 
associated with a hardware resource (for example, a data set) . 

The transaction identification is used only for the current ATTACH; 
it is not carried in the TCA for the duration of the task. 

The specified task is not attached if the transaction identification 
is not in the PCT or the program name is not in the Processing Program 
Table (PPT) . If this situation exists or the attached task ABENDS, a 
message is sent to the terminal operator, but the attaching task is not 
notified of the condition. Therefore, the DFHKC TYPE=ATTACH macro 
instruction must i>e used with extreme caution by the application 
programmer. 

Although the application programmer has the capability of attaching a 
task directly to a terminal by means of the DFHKC TYPE=ATTACH macro, 
this procedure is not recommended. (The DFHKC TYPE=ATTACH macro cannot 
be used to attach a task to a VTAM logical unit.) Instead, one of the 
following approaches should be used: 

• Automatic task initiation through transient data management 

• Automatic task initiation through time management (interval control 
program); for example, a DFHIC TYPE=INITIATE macro with a zero 
interval 

• Identification of the transaction identification to be used with 
the next input message from the terminal by means of a DFHPC 
TYPE=RETORN,TRANSID= macro instruction. 

The flowchart in Figure 5.3—1 shows Task A attaching Task B and 
synchronizing the processing steps of both tasks through use of the 
facility control address passed to the newly created task at attach 
time. Since Task B is a nonterminal— oriented task, it is unable to use 
terminal control macro instructions. FCADDR specifies the address of 
Task A»s TCA; ECB1 and ECB2 are fields in the TWA for Task A. 

Figure 5*3—1 includes steps labeled "POST ECB" . Posting an ECB 
entails setting on the appropriate bit in the ECB, which is a 4— byte 
field. In CICS/OS/VS, the bit to be set on (that is, set to ■ 1") is bit 
1 of byte 0; in CICS/DOS/VS, it is bit of byte 2. The following 
examples show how to set bits on for each programming language. These 
examples set on both the bit required for CICS/OS/VS and that required 
for CICS/DOS/VS, so they may be used for both systems. 
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For Assembler lang uage: 

ECB1 DC F'O 1 

HVC BCB1 (3) ,=X»400080» 



For COBOL : 

77 ECB1 PIC S9 (8) COHP VALUE ZERO 



PROCEDURE DIVISION. 

COHPUTE ECB1 = 2 ** 15 + 2 ** 30. 



Foff PL/I: 



DCL ECB1 BIT(32) ALIGNED INIT(«0»B); 
ECB1 = B 01000000000000001»B; 
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TASK A 



Attach Task B 

and Point FCADDR 

toTCA 




If Task 'B' is lower 
— in priority it becomes 
active here. 



TASKB 

Obtain Address of 
ECB1 and ECB2 by 

Use of Address 
Now in TCAFCAAA 



YES 



NO 



Wait on ECB1 
(Notel) 



If Task 'B' is higher 

in priority it becomes 

active here. 



Processing Step 1 



Post ECB1 to Make 
Task 'A' Oispatchable 



Task 'A' is aware if 
Task 'B' completed 
Processing Step 1 . 



Processing Step 2 



Wait on ECB2 
(Note 2) 



Task 'B' is aware 

of completion 

of both Step 1 
and Step 2. 



Task 'B' gives up 
control here. 



Task 'B' regains 
control here. 



Post 
ECB2 



Processing Step 3 



Give Up Control 
By a Wait or PC Return 



Note 



If Task B is not attached 
(e.g. Trans ID not in PCT), 
or if Task B ABEND, ECB 1 
may never be posted. 



Note 2: If Task A ABEND, ECB2 
may never be posted. 



Figure 5*3—1. Task Synchronization under CICS/VS 

The DFHPC TYPE=RETURN macro instruction can be used to terminate any 
tasks initiated by the application programmer through use of the task 
control DFHKC TIPE=ATTACH macro instruction. 

The following example illustrates the coding reguired to statically 
provide a facility control area address and transaction identification: 
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DFHKC TYPE=ATTAC'd, 

FCADDR=FACCTL, 
TRANSID=TRN1 



INITIATE NEW TASK 
USER'S FCA ADDRESS 
TRANSACTION IDENTIFICATION 



The following examples illustrate the coding required to dynamically 
provide a facility control area address and transaction identification. 



F or Assembler lanqnaqe : 

MVC TCAKCTI,=CL4'TRN1' 
MVC TCAKCFA,=A (FACCTL) 



TRANSACTION IDENTIFICATION 
USER'S FCA ADDRESS 



DFHKC TYPE=ATTACH 



INITIATE NEW TASK 



For COBOL: 



MOVE 'TRN1« TO TCAKCTI 
MOVE FACADR TO TCAKCFA, 



NOTE TRANSACTION IDENTIFICATION 
NOTE USER'S FCA ADDRESS. 



DFHKC TYPE=ATTACH 



INITIATE NEW TASK 



For PL/I: 



TCAKCTI='TRH1 •; 
TCAKCFA=FACADR; 



/♦TRANSACTION IDENTIFICATION*/ 

/♦USER'S FCA ADDRESS*/ 

/♦FACADR IS A POINTER VARIABLE*/ 



DFHKC TYPE=ATTACH 



INITIATE NEW TASK 
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Change Priority of a Task (TYPE=CHAP) 

The format of the DFHKC macro instruc, ion to change the dispatching 
priority of a task is as follows: 



1 1 1 

I I I 

| DFHKC | TYPE=CHAP I 

j J [ ,PRTY=priority value] I 

I I I 
i i i 1 

The overall transaction processing priority of a task is the sum of 
related transaction, terminal, and operator priorities as specified or 
established by default at system generation* This priority determines 
the position of the task in the dispatching priority queue and, 
therefore, its scheduling under CICS/VS. The priority of an existing 
task can be changed by issuing the DFHKC TYPE=CHAP macro instruction. 
The specified priority value must be in the range from through 255, 
where 255 represents the highest priority. This task is placed below 
all other tasks of egual or higher priority in the dispatching priority 
queue. 

The application programmer can include the PRTY=priority value 
operand in the DFHKC TYPE=CHAP macro instruction to assign a new 
dispatching priority to a task. Alternatively, the programmer can 
assign a priority value to the dispatching priority field (TCATCDP) 
prior to issuing the DFHKC TYPE=CHAP macro instruction. 

A task can relinquish control to all tasks of equal or higher 
priority by issuing a DFHKC TYPE=CHAP macro instruction. No priority 
value need be specified, and the current priority value of the tasK as 
stored in TCATCDP is not changed. However, the fact that the macro 
instruction is issued permits control to be transferred from the task 
issuing the instruction to an equal or higher priority task within 
CICS/VS. This capability is designed particularly for compute-bound 
tasks which, by continually demanding inordinate amounts of processor 
time, can significantly affect overall system performance. 

The following example snows how to statically assign a new task 
dispatching priority value: 

DFHKC TYPE=CHAP, CHANGE PRIORITY OF THIS TASK * 

PRTY=2 55 NEW PRIORITY VALUE 

The following examples illustrate the coding required to assign a 
dynamically selected priority value. This value can be specified as a 
binary, decimal, or hexadecimal number, depending on the programming 
language used. 
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For Assembler language : 
MVI TCATCDP,X»FF« 



ASSIGN NEW PRIORITY VALUE 



DFHKC TYPE=CHAP 



CHANGE PRIORITY OF THIS TASK 



For COBOL ; 

MOVE HIGH-VALUES TO TCATCDP. NOTE ASSIGN NEW PRIORITY VALUE 



DFHKC TYPE=CHAP 



CHANGE PRIORITY OF THIS TASK 



For PL/I : 
| TCATCDP= , 11111111»B; 



/♦ASSIGN NEW PRIORITY VALUE*/ 



DFHKC TYPE=CHAP 



CHANGE PRIORITY OF THIS TASK 
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Synchronize a Task (TYPE=WAIT) 

The format of the DFHKC macro instruction to synchronize the execution 
of a task with the completion of an event, or to relinquish control to a 
tasJc of higher priority, is as follows: 



I" - 

1 


r — - r i 

1 1 

DFHKC | TYPE=WAIT I 

| [ ,DCI= {SINGLE | LIST! DISP | CICS} ] | 

| [ ,ECADDR=symbolic address] I 

1 1 

i i 1 



The application programmer can synchronize a task with the completion 
of an event or one of a list of events initiated by the same task or by 
another task, or relinquish control to a task of higher dispatching 
priority, by issuing the DFHKC TYPE=WAIT macro instruction. In the 
first case, this macro instruction provides a method of directly 
relinquishing control to some other task until the event being waited on 
is completed. In the latter case, the task remains dispatchable . That 
is, execution of the task is resumed if no task of higher priority is 
ready to be processed. 

The application programmer must specify the circumstances under which 
synchronization of a task is to occur by including the DCI=keyword 
operand (dispatch control indicator) . 

If the task is to be synchronized with the completion of a single 
event or an event in a list of events, the application programmer must 
specify the symbolic address of either the single event control area or 
the list of event control areas. The address can be specified by 
including the ECADDR=symbolic address operand in the DFHKC TYPE=»AIT 
macro instruction, or by coding a single instruction that places the 
event control address in TCATCEA prior to issuing tne DFHKC TYPE=WAIT 
macro instruction. In either case, the referenced event control area (s) 
must conform to the format and standard posting conventions of ECBs. 
Examples showing how to post ECBs are given in the section "Initiate a 
Task (ATTACH) ," earlier in this chapter. An event control area can also 
be the timer event control area referred to in a DFHIC TIPE=POST macro 
instruction. (See the discussion of task synchronization in Chapter 
5.2.) In a CICS/OS/VS system, if two tasks are allowed to wait on the 
same event control area, CICS/VS may terminate abnormally. 



SYn chro nize a T ask with a Single Event 

The DFHKC TYPE=HAIT, DCI=SINGLE macro instruction is used by the 
application programmer to synchronize a task with the completion of a 
single event initiated by the same task or by another task. 

The following example shows how to synchronize a task with a single 
event, statically providing the symbolic address of the appropriate 
event control area: 

DFHKC TYPE=WAIT, RELINQUISH CONTROL OF CICS/VS * 

DCI=SINGLE, WAIT ON SINGLE EVENT * 

ECADDR=EVENTCTL ADDRESS OF EVENT CONTROL AREA 
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The following examples show how to synchronize a task with a single 
event, dynamically providing the symbolic address of the appropriate 
event control area. 



For Assembler language ; 

ST SINGADDR,TCATCEA PLACE SYMBOLIC ADDRESS IN TCA 



DPHKC TYPE=WAIT, 
DCI=SINGLE 



RELINQUISH CONTROL OF CICS/VS 
WAIT ON SINGLE EVENT 



For COBOL ; 

MOVE SINGADDR TO TCATCEA * NOTE PLACE SYMBOLIC ADDR IN TCA 



DFHKC TYPE=WAIT, 
DCI=SINGLE 



RELINQUISH CONTROL OF CICS/VS 
WAIT ON SINGLE EVENT 



F or PL/ I; 

TCATCEA=SINGADDR; 



/♦PLACE SYMBOLIC ADDRESS IN TCA*/ 
/♦SINGADDR IS A POINTER VARIABLE*/ 



DFHKC TIPE=WAIT, 
DCI=SINGLE 



RELINQUISH CONTROL OF CICS/VS 
WAIT ON SINGLE EVENT 
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Sync hronize a Task with One of a List._of Events 



The DFHKC TYPE=WAIT,DCI=L1ST macro instruction is used by the 
application programmer to synchronize a task with the completion of one 
event of a list of events. This list consists of a series of contiguous 
four— byte fields, each field containing the symbolic address of a single 
event control area. The last four— byte field of the list contains 
binary ones, hexadecimal •FF's, or the card code (multipunch) 12—11—0—7— 
8-9. 

The following example shows how to synchronize a task with one of a 
list of events, statically providing the symbolic address of the 
appropriate list of events: 



DFHKC TYPE=WAIT, 
DCI=LIST, 
ECADDR=TOPOLIST 



RELINQUISH CONTROL OF CICS/VS * 
WAIT ON A LIST OF EVENTS * 

ADDRESS OF LIST OF EVENTS 



The following examples show how to synchronize a task with one of a 
list of events, dynamically providing the symbolic address of the 
appropriate list of events. 



Fo r Assembler language : 

ST LISTADDR,TCATCEA 



PLACE SYMBOLIC ADDRESS IN TC A 



DFHKC TYPE=WAIT, 
DCI=LIST 



RELINQUISH CONTROL OF CICS/VS 
WAIT ON A LIST OF EVENTS 



F or COBOL : 

MOVE LISTADDR TO TCATCEA 



NOTE PLACE SYMBOLIC ADDR IN TCA , 



DFHKC TYPE=ffAIT, 
DCI=LIST 



RELINQUISH CONTROL OF CICS/VS 
WAIT ON A LIST OF EVENTS 



TCATCEA=LISTADDR; 



DFHKC TYPE=WAIT, 
DCI=LIST 



/♦PLACE SYMBOLIC ADDRESS IN TCA*/ 
/♦LISTADDR IS A POINTER VARIABLE*/ 

RELINQUISH CONTROL OF CICS/VS 
WAIT ON A LIST OF EVENTS 



Relinquish Control to a Task o f Higher Priority 



The DFHKC TYPE=HAIT,DCI=DISP macro instruction is used by the 
application programmer to voluntarily relinquish control to a task of 
higher dispatching priority. Control is returned to the task issuing 
the macro instruction if no other task of a higher priority is ready to 
be processed. 
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When binary synchronous communication lines are part of the use^s 
configuration, these lines may time out if excessive processor time is 
required by an application program. One way to avoid this condition is 
to include one or more DPHKC TIPE=WAIT,DCI=DISP macro instructions in 
the application program to voluntarily relinquish control before the 
line time— out can occur. 

The following example shows how to voluntarily relinquish control to 
a task of higher dispatching priority: 

DFHKC TYPE=WAIT, RELINQUISH CONTROL OF CICS/VS * 

DCI=DISP AND REMAIN DISPATCHABLE 

Note : The DFHKC TYPE=RAIT macro instruction differs from a TYPE=CHAP 
macro instruction that does not indicate a priority in that the former 
relinquishes control only to a task of higher priority, while the latter 
may relinquish control to a task of either equal or higher priority. 
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Enqueue Upon a Resource (TYPE=ENQ) 

The format of the DFHKC macro instruction to enqueue upon a resource, 
causing execution of a task to be synchronized with the availability of 
that resource, is as follows: 



1 

I 
DFHKC | TYPE=ENQ[ ,COND=YES | NO ] 

| [ ,QARGADE=symbolic address] 
| [ ,QARGLNG=number ] 

I 

i 

In the CICS/VS environment, where tasks are processed concurrently, 
it is sometimes desirable to protect a given resource from concurrent 
use by multiple tasks. In effect, the resource can be treated as 
serially reusable. To provide this resource protection, an installation 
convention must be estaolished for all application programaers to 
follow. 

The convention is based on use of the DFHKC TYPE=EHQ macro 
instruction, identifying the resource by a symbolic address or a 
character— string argument. When executed, this macro instruction causes 
further execution of the task issuing the instruction to be synchronized 
with the availability of the specified resource; control is returned to 
the task when the resource is available. When all tasks accessing a 
resource adhere to the convention of engueuing upon the resource, the 
resource is afforded "single-server" protection. 

When a single-server resource is being used by a task and other tasks 
concurrently enqueue upon the same resource, the first task to issue the 
DFHKC TYPE=ENQ macro instruction receives the resource when it becomes 
available. The other tasks obtain the resource, in turn, in the order 
in which they enqueue upon iti 

For assembler— language application programs only, when COND=YES is 
specified, control is returned to the requesting transaction whether or 
not the requested resource is available; task control places a return 
code in TCATCTR indicating the result of the engueue request. The 
return codes and their meanings are: 

TCATCOK The requested resource has been given to the requestor 

TCATCONQ The requested resource is not available 

TCADUPQ The requestor already has the requested resource 

COND=NO is the default, and when this is specified, either explicitly 
or by default, the normal enqueue mechanism operates (that is, the 
requestor is enqueued upon the resource if it is not immediately 
available) . 
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When issuing the DFHKC TYPE=ENQ macro instruction, the application 
programmer must identify the single—server resource he is enqueuing upon 
by one of the following methods: 

1. Specify a symbolic main storage address that represents the single- 
server resource. The application programmer must provide the 
symbolic main storage address in the DFHKC TYPE=ENQ macro 
instruction or by coding instructions (prior to issuing the DFHKC 
TYPE=ENQ macro instruction) that place the address in the low— order 
three bytes of TCATCQA, a four— byte field. He must place binary 
zeros in the high— order byte. 

2. Specify a symbolic main storage address that contains a unique 
character-string argument (for example, an employee name) that 
represents the single— server resource. The unique argument may be 
up to 255 bytes in length, beginning at the location pointed to by 
the contents of the specified address. The application programmer 
must provide the symbolic main storage address and the length in 
the DFHKC TYPE=ENQ macro instruction or by coding instructions 

(prior to issuing the DFHKC TYPE=ENQ macro instruction) that place 
the symbolic address in the low— order three bytes of TCATCQA, a 
four— byte field, and the length (in bytes) in the high— order byte. 
CICS/VS task control makes a copy of this pointer in its storage 
for use in controlling the resource. 
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Dequeue Upon A Resource (TYPE=DEQ) 



The format of the DFHKC macro instruction to dequeue upon a resource 
(effectively, to revoke a preceding enqueue request upon that resource) 
is as follows: 



DFHKC | TYPE=DEQ 

| [ ,QARGADR=symbolic address] 
| [ ,QARGLNG=number ] 



When issuing the DFHKC TYPE=DEQ macro instruction, the application 
programmer must identify the resource he is dequeuing by the method that 
was used in enqueuing. The COBOL programmer may find it convenient to 
use the program control DFHPC TYPE=COBADDR macro instruction (see the 
example below) if preloading of the address is desired. 

If a task enqueues upon a resource but does not dequeue it, task 
control automatically dequeues the single— server protection request upon 
termination of the task. 

The following examples show how to enqueue upon a single— server 
resource using method 1, aoove. Substituting "DEQ" for "ENQ" in these 
examples illustrates the ways in which the application programmer can 
release single-server protection from a resource prior to termination of 
the associated task. 



For Assemble r langu age : 

COPY DFHCSADS 
CSAWABA DS F 



DFHKC TYPE=ENQ, 

QARGADR=CSAWABA 



ENQ ON SINGLE-SERVER RESOURCE 
SPECIFY SYMBOLIC ADDRESS 



OR 

LA HORKREG,CSAWABA 
ST WORKREG,TCATCQA 



DFHKC TYPE=ENQ 
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For COBOL: 



01 DFHCSADS COPY DFHCSADS* 
02 CSAWABA PIC X(50) . 



MOVE ZEROS TO TCATCQA. 
DFHKC TYPE=ENQ, 

QARGADR=CSAWABA 



ENQ ON SINGLE-SERVER RESOURCE 
SPECIFY SYMBOLIC ADDRESS 



OR 

DFHPC TYPE=COBADDR, 
LABEL=CSAWAB& 
MOVE TCAPCLA TO TCATCQA 



DFHKC TYPE=ENQ 



For PL/I ; 



^INCLUDE DFHCSADS; 

DECLARE 1 DFHEXCSA BASED (CSACBAR) , 

2 FILLER CHAR (512), 

2 CSAWABA CHAR (50) ; 



DFHKC TYPE=ENQ, 

QARGADR=CSAWABA 



ENQ ON SINGLE-SERVER RESOURCE 
SPECIFY SYMBOLIC ADDRESS 



OR 



TCATCOA=ADDE 'CSAWABA* 



DFHKC TYPE=ENQ 

The following examples show how to enqueue upon a single-server 
resource using method 2. The resource to be enqueued upon is identified 
by the nine— character social security number in a field labeled 
SOCSECNO. Task control makes a copy of this field for its use in 
controlling the resource. 

Substituting "DEQ" for "ENQ" in these examples illustrates the ways 
in which the application programmer can release single— server protection 
from a resource prior to termination of the associated task. 



F or Assembler language ; 

DFHKC TYPE=ENQ, 

QARGADR=SOCSECNO, 
QARGLNG=9 



OR 

LA WORKREG, SOCSECNO 
ST WORKREG r TCATCQA 
MVI TCATCQAL,X»09» 
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DFHKC TYPE=ENQ 



For COBOL; 



DFHKC TYPE=BNQ, * 

QARGADR=SOCSECNO, * 

QARGLNG=9 



For PL/I : 



DFHKC TYPE=ENQ, * 

QARGADR=SOCSECNO, * 

QARGLNG=9 

OR 

^INCLUDE DFHTCADS; 

DECLARE 1 DFHEXTCA BASED (TCACBAR) , 

2 FILLER CHAR (20), 

2 TCATCQAL BIT (8) ; 



TCATCQA=ADDR (SOCSECNO) ; 
TCATCQAL=»00001001 »B; 



DFHKC TYPE=ENQ 
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Declare a Task to be Purgeable (TYPE=PURGE) 

The format of the DFHKC macro instruction to declare that a task may be 
purged if a system stall condition occurs is as follows: 

i 1 1 1 

III I 

| | DFHKC | TYPE=PURGE | 

III I 

i i I i 

Certain overload conditions, where all of a given system resource 
(for example, main storage) has been allocated and where each task 
requires still more of that resource, can occur in CICS/VS. The result 
is a situation in which no task is able to continue processing and no 
new task can be initiated; the system stalls. 

CICS/VS has the capability of detecting certain system stall 
conditions and taking corrective action. Corrective action consists, in 
part, of purging (deleting) the lowest priority task in the system that 
is designated as stall purgeable. 

A task is initially defined as purgeable or not purgeable in the 
program control table (PCT) entry associated with the transaction 
identification for that task. This entry is established by the system 
programmer at system generation. The application programmer can 
dynamically change the purgeability status of a task by issuing the 

DFHKC TYPE=PURGE 

macro instruction to indicate that the task is purgeable, or the 

DFHKC TYPE=NOPURGE 

macro instruction to indicate that the task is not purgeable. The 
designated status remains in effect for that task until another change 
is initiated or until the task is terminated. For example, a long- 
running task may issue a DFHKC TYPE=NOPURGE macro instruction prior to 
critical processing, then issue a DFHKC TYPE=PURGE macro instruction 
after that processing is completed. This ensures that the task is not 
stall— purged during the critical processing. 



Declare a Task to be Nonpurgeable (TYPE=NOPURGE) 

The format of the DFHKC macro instruction to declare that a task cannot 
be purged if a system stall condition occurs is as follows: 



i 1 

I I 

| DFHKC | TYPE=NOPURGE 



Note : The PURGE and NOPURGE options of the DFHKC macro are intended to 
be used as temporary overrides to the SPURGE specification in the DFHPCT 
TYPE=ENTRY macro for a task. For example, if a DFHKC TYPE=NOPURGE macro 
is issued in a program for a task, the task cannot be purged even though 
SPURGE=YES is specified in the DFHPCT TYPE=ENTRY macro for the task at 
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system generation. Refer to the publication CICS/VS System Programmer's 
Reference Manual for details about the SPURGE option of the DPHPCT 
TYPE=ENTRY macro. 
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Operands of DFHKC Macro 



COND= 



DCI= 



specifies whether or not an enqueue is to be conditional 
(assembler language only) . 



YES 



NO 



the enqueue request is conditional* Control is returned to 
the requestor whether or not the requested resource is 
available. A return code at TCATCTR indicates the result 
of the request: 



TCATCOK The resource has been given to the requestor 

TCATCONQ The resource is not available 

TCADUPQ The requestor already has the resource 



the enqueue is not conditional. If the requested resource 
is not immediately available, the requesting transaction 
will be enqueued upon it. COND=NO is the default. 



specifies when synchronization is to occur* 

SINGLE 

indicates that the task is to be synchronized with the 
completion of a single event. 

LIST 

indicates that the task is to be synchronized with the 
completion of one event in a list of events. 

DISP 

indicates that the task wishes to give up control to any 
higher priority task that is ready to be processed; if none 
exists, control is to be returned to this task. 

CICS 

• CICS/OS/VS only and assembler language only 

indicates that the ECB will be posted by another 
transaction rather than by the operating system. This 
option means that the ECB will not be added to the 
operating system WAIT macro issued by CICS/VS. ECBs to be 
posted by other transactions should reside in permanent 
storage. 

Tasks that wish to synchronize with each other as 
illustrated in figure 5.3—1, may do so by using either 
DCI=CICS or DCI=SINGLE (CICS/DOS/VS must use DCI=SINGLE 
only). DCI=CICS must be used if more than one 
synchronizing task is going to wait on the same ECB. In 
all other cases it is preferable to use DCI=SINGLB. 



386 CICS/VS APRM(ML) 



ECADDR=symbolic address 

is used with DCI=SINGLE or DCI=LIST to specify the symbolic 
address of the single event control area or list of event 
control areas identifying the event with which this task is to 
be synchronized; if omitted when SINGLE or LIST is specified, 
the address is assumed to be in TCATCEA. 

FCADDR=symbolic address 

is the symbolic address of the facility control area (PCA) 
associated with this task; if omitted, the address is assumed 
to be in TCAKCFA. 

PRTI=priority value 

is a decimal numeral in the range from through 255 to be 
taken as the priority value for this task; if omitted, the 
priority value is assumed to be in TCATCDP. 

QARGADR=symbolic address 

is either the symbolic address of the resource to be enqueued 
or dequeued, or the symbolic address of a location that 
contains a unique argument (for example, an employee name) that 
represents the resource* If this operand is omitted, the 
address is assumed to be in the three low— order bytes of 
TCATCQA, a four— byte field. 

QARGLNG=number 

is the length, in bytes, of the resource to be enqueued upon or 
to be dequeued. This operand is needed only if the QARGADR 
operand is a unique argument that represents the resource to be 
enqueued. If omitted in such a case, the contents of the high- 
order byte of TCATCQA are assumed to be the length of the 
argument. COBOL programs must not use this operand unless the 
QARGADR operand is used. 

TRANSID=name 

is the transaction identification for the task; if omitted, the 
transaction identification is assumed to be in TCAKCTI. 
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All program communication within CICS/VS is accomplished by program 
management. The program management macro instruction (DFHPC) is used to 
request any of the following services: 

• Link one user— written application program to another, anticipating 
subsequent return to the requesting program (TYPE=LINK) . 

• Transfer control from one user— written application program to 
another, anticipating no return to the requesting program 
(TYPE=XCTL) . 

o Load a designated application program, table, or map (generally, 
for use with basic mapping support) into main storage and return 
control to the requesting program (TYPE=LOAD) . 

• Return control from one user— written application program to another 
or to CICS/VS (TYPE=RETURN) . 

o Delete a previously loaded application program from main storage 
(TYPE=DELETE) . 

• Abnormally terminate a transaction and its related task 

(TYPE=ABEND). 

• Activate, cancel, or reactivate an exit tnat permits user— written 
abnormal termination processing (TYPE=SETXIT or TYPE=RESETXIT) . 

• Convert a symbolic label in a COBOL program into an address which 
is returned in TCAPCLA (TYPE=COBADDR) . 

Application programs running under CICS/VS are executed at various 
logical levels. For example, where one user— written application program 
is linked to another, the linked— to program is considered to reside at 
the next lower logical level. Where control is simply transferred from 
one application program to another, the two programs are considered to 
reside at the same logical level. A DFHPC TYPE=LINK macro instruction 
is used for the former; a DFHPC TYPE=XCTL macro instruction (where XCTL 
means transfer control) is used for the latter. Figure 5.4—1 
illustrates this difference between program linkage and transfer of 
program control* Each of the programs shown in this figure may have 
been written in any of the CICS/VS— supported languages (Assembler 
language, COBOL, and PL/I). Use of LINK, XCTL, RETURN, and ABEND is 
explained in greater detail below. 

Tasks can share the use of common work areas. However, each task 
requires the use of a unique intermediate storage area, such as the 
transaction work area (TWA) , to retain information needed upon 
subsequent return to that task. The application programmer must provide 
addressability to that intermediate storage area by symbolically 
defining it in his program. 

Parameters can be passed from one program to another in the same task 
through user— defined storage areas, for example, the transaction work 
area (TWA) , the terminal input/output area (TIOA) , the terminal control 
table terminal entry (TCTTE), or the file work area (FWA). 

CICS/VS automatically saves program control information and general- 
purpose registers, when applicable, in the task control area (TCA) . 
CICS/VS automatically restores general— purpose registers, as necessary, 
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to return control to a program. The name of any program referred to in 
a request for program services must have been placed in the processing 
program table (PPT) prior to execution of CICS/VS. 



CICS/VS 
Program 
Control 



Application 

Program 

A 



LINK 



RETURN 



XCTL 



Application 

Program 

B 



Application 

Program 

C 



LINK 



RETURN 



XCTL 



Application 

Program 

D 



Application 
Program 

E 



RETURN 



figure 5.4—1* Logical Relationship of Application Programs 
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Pass Program Control Anticipating Return (TYPE=LINK) 

The format of the DFHPC macro instruction to pass control to an 
application program at the next lower logical level is as follows: 




TYPE=LINK 

[ ,PROGRAM=name ] 

[ ,COND=YES] 

[ ,NORESP=symbolic address] 

[ ,PGMIDER=symbolic address] 



When a DFHPC TYPE=RETURN macro is executed in the linked— to program, 
control is returned to the first program at the next seguential 
(executable) instruction. 

The application programmer must specify the name of the program to 
which control is to be passed in the PROGRAM operand or in a single 
instruction that places the program name in TCAPCPI prior to issuing 
this macro instruction. The COND operand specifies that control will be 
returned to the first program if the specified program is disabled or 
its name cannot be found in the PPT. 

The following example shows how to request a link to an application 
program: 

DFHPC TYPE=LINK, * 

PR0GRAM=PR0G1 

The following examples show how to link to an application program 
specified by an instruction executed prior to DFHPC TYPE=LIHR. 

F or Assembler languag e : 

MVC TCAPCPI, =CL8»PR0G1 ■ PLACE LIHKED-TO PROGRAM NAME IH TCA 



DFHPC TYPE=LINK 



LINK TO PROGRAM AT NEXT LOWER LEVEL 



For COBOL ; 

MOVE » PR0G1» TO TCAPCPI. MOTE LINKED-TO PROGRAM NAME TO TCA. 



DFHPC TYPE=LINK 



LINK TO PROGRAM AT NEXT LOHER LEVEL 



F or PL/I : 

TCAPCPI= , PR0G1«; 



/♦PLACE LINKED-TO PRGH NAHE IN TCA*/ 



DFHPC TYPE=LINK 



LINK TO PROGRAM AT NEXT LOWER LEVEL 
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Transfer Program Control (TYPE=XCTL) 

The format of the DFHPC macro instruction to pass (transfer) control to 
an application program at the same logical level is as follows: 



DFHPC | TYPE=XCTL 

I [ ,PROGRAM=name] 



This macro specifies that program control is transferred from one 
user— written application program to another at the same logical level. 
The program from which control is transferred is released. Any return 
from the transferred—to program is to a program from which there was an 
exit at the next higher logical level. If there is no user— written 
application program at the next higher logical level, control is 
returned to CICS/VS* 

The application programmer must specify the name of the program to 
which control is to be transferred in the PROGRAM operand or in a single 
instruction that places the program name in TCAPCPI prior to issuing 
this macro instruction. The field TCAPCPI is eight bytes in length. If 
the program name is less than eight bytes, the field must be padded on 
the right with blanks. 

The following example shows how to reguest a transfer of control to a 
particular application program: 

DFHPC TYPE=XCTL, * 

PR0GRAM=PR0G2 

The following examples show how to transfer control to an application 
program specified by an instruction executed prior to DFHPC TYPE=XCxL. 

F or Assembler language : 

MVC TCAPCPI,=CL8«PROG2« PLACE TR ANSFERRED-TO PRGM NAME IN TCA 

DFHPC TYPE=XCTL TRANSFER PROGRAM CONTROL 

For C OBOL : 

MOVE »PR0G2» TO TCAPCPI. NOTE TRANSFERRED-TO PRGM NAME TO TCA. 

DFHPC TYPE=XCTL TRANSFER PROGRAM CONTROL 

For PL/I : 

TCAPCPI=»PR0G2«; /*PLACE PROGRAM NAME IN TCA*/ 

DFHPC TYPE=XCTL TRANSFER PROGRAM CONTROL 
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Load a Program (TYPE=LOAD) 



The format of the DFHPC macro instruction to load a program, table, or 
map from its location in a CICS/VS program library is as follows: 




TYPE=LOAD 

[ , PROGRAM =name] 

[ ,LOADLST=NO] 

[ ,COND=YES] 

[ ,NORESP=symDolic address] 

[ ,PGMIDER=symbolic address] 



This macro specifies that programs, tables, or maps are to be fetched 
from the library where they reside and loaded into main storage. This 
facility is used to (1) load a program that will Jae used repeatedly, 
thereby reducing system overhead through a one— time load, (2) load a 
table to which control is not to be passed, or (3) load a map to be used 
in a mapping operation (see Chapter 4.3) . CICS/VS returns the address 
of the loaded program in TCAPCLA. 

The loaded program remains in main storage until the DFHPC 
TYPE=DELETE macro instruction is issued or until the task that issued 
the DFHPC TYPE=LOAD is terminated, either normally or abnormally (unless 
LOADLST=NO is specified) . If LOADLST=NO is specified, the loaded 
program remains resident until it is deleted by this, or another, task. 

The application programmer must provide the name (identification) of 
the program to be loaded in the DFHPC TYPE=LOAD macro instruction or in 
a single instruction that places the program name in TCAPCPI prior to 
issuing the DFHPC TYPE=LOAD macro instruction. 

The following example shows how to load a user-written application 
program: 

DFHPC TYPE=LOAD, 

PR0GRftM=PR0G3 

The following examples show how to load an application program 
specified dynamically by an instruction executed prior to DFHPC 
TYPE=LOAD. 



F or Assembler language : 

MVC TCAPCPI,=CL8»PROG3» PLACE PROGRAM NAME IN TCA 



DFHPC TYPE=LOAD 



LOAD THE SPECIFIED PROGRAM 



For COBOL 



MOVE «PR0G3« TO TCAPCPI. NOTE PLACE PRGM NAME IN TCA 



DFHPC TYPE=LOAD 



LOAD THE SPECIFIED PROGRAM 
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F or PL/I : 

TCAPCPI= , PR0G3 I ; /*PLACE PROGRAM NAME IN TCA*/ 

DFHPC TYPE=LOAD LOAD THE SPECIFIED PROGRAM 
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Return Program Control (TYPE=RETURN) 



The format of the DFHPC macro instruction to return control from an 
application program to the program at the next higher logical level is 
as follows: 



1 

I 
DFHPC | TYPE=RETURN 

I [ ,TRANSID=transaction code] 



When this macro instruction is executed in a lower level (linked— to) 
program, it restores the registers of the higher level (linked— from) 
program to their contents at the time the DFHFC TYPE=LINK was issued and 
releases save areas for the lower— level program. In general, the 
program to which control is returned must have relinguished control by 
execution of a DFHPC TYPE=LINK macro instruction and must reside one 
logical level higher than the program returning control. Upon normal 
termination of transaction processing, control is returned to CICS/VS. 

If no default transaction code has been assembled into the terminal 
control table terminal entry (TCTTE) for a particular terminal, the 
application programmer can specify the transaction identification for 
the next program to be associated with that terminal in either of two 
ways: (1) by including the desired transaction identification in the 
DFHPC TYPE=RETURN macro instruction, or (2) by coding a single 
instruction that places the desired transaction identification in 
TCANXTID prior to issuing the DFHPC TYPE=RETURN macro instruction. By 
doing so, the programmer ensures that subseguent unsolicited input can 
be entered from the terminal without the specification of a transaction 
identification. A flexible means of starting the next task is thus 
provided. 

Note, however, that the methods of specifying the transaction 
described above may be overridden by issuing BMS paging commands. (See 
"Terminal -Oriented Task Identification," in Chapter 4.2, for a precise 
description.) 
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Delete a Loaded Program (TYPE=DELETE) 



The format of the DFHPC macro instruction to delete a previously loaded 
program is as follows: 



I DFHPC | TYPE=DELETE 

| | [,PROGRAM=name] 



This macro specifies that a program previously loaded through use of 
the DFHPC TYPE=LOAD macro instruction with or without the LOADLST=NO 
operand is to be deleted. If the DFHPC TYPE=LOAD macro instruction 
contained LOADLST=NO, the loaded program is deleted only in response to 
a DFHPC TYPE=DELETE macro instruction. If LOADLST=NO is not specified, 
the loaded program can be deleted by a DFHPC TYPE=DELETE reguest, or it 
will be automatically deleted when the task that issued the load reguest 
is terminated. 

The application programmer must specify the name (identification) of 
the program to be deleted in the DFHPC TYPE=DELETE macro instruction or 
in an instruction that places the program name in TCAPCPI prior to 
issuing the DFHPC TYPE=DELETE macro instruction. 

The following example shows how to delete a user— written application 
program loaded in response to a DFHPC TYPE=LOAD macro instruction. 

DFHPC TYPE=DELETE, 
PR0GRAM=PR0G4 

The following examples show how to dynamically delete an application 
program xGaucu in response to a DFHPC TYPE— LOAD macro instruct ion. 

F or Assembler languag e : 

MVC TCAPCPI,=CL8»PROG4» PLACE PROGRAM NAME IN TCA 



DFHPC TYPE=DELETE 



DELETE THE SPECIFIED PROGRAM 



F or COBOL : 

MOVE •PR0G4» TO TCAPCPI. NOTE PLACE PRGM NAME IN TCA. 



DFHPC TYPE=DELETE 



DELETE THE SPECIFIED PROGRAM 



For PL/I : 

TCAPCPI=»PR0G4»; 



/♦PLACE PROGRAM NAME IN TCA*/ 



DFHPC TYPE=DELETE 



DELETE THE SPECIFIED PROGRAM 
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Abnormally Terminate a Transaction (TYPE=ABEND) 



The format of the DFHPC macro instruction to abnormally terminate a 
transaction (task) is as follows: 



DFHPC I TYPE=ABEND 

[ ,ABCODE={value|YES} ] 
[ ,CANCEL=YES] 



This macro specifies that a transaction and its related task is to be 
terminated abnormally. If a task is attached by another task, only the 
task that issues the ABEND is terminated. The main storage associated 
with the terminated transaction is released. If CANCEL=YES is 
specified, all exits established by DFHPC TYPE=SETXIT macro instructions 
at any level in the task are canceled. 

The application programmer can request a dump of main storage related 
to the terminated transaction. The request must specify a four- 
character abnormal termination code that dump control will place in the 
formatted storage dump to identify the ABEND condition. This code can 
be specified in either of two ways: 

1. It can be specified in the TYPE=ABEND macro instruction, as 
follows: 



2. 



DFHPC TYPE=ABEND, 
ABCODE=1234 

It can be placed in TCAPCAC before issuing the macro instruction, 
as follows: 



F or Assembler languag e : 

MVC TCAPCAC, =CL4» 1234" PLACE TERMINATION CODE IN TCA 



DFHPC TYPE=ABEND, 
ABCODE=YES 



TERMINATE PGRM , TRANS, 5 TASK 
USE ABCODE ALREADY SPECIFIED 



For COBOL : 

MOVE •123U* TO TCAPCAC, 



NOTE TERMINATION CODE TO TCA. 



DFHPC TYPE= ABEND, 
ABCODE=YES 



TERMINATE PGRM, TRANS, & TASK 
USE ABCODE ALREADY SPECIFIED 
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For PL/I ; 

TCAPCAC=« 1234 •; /*PLACE TERMINATION CODE IN TCA*/ 



DPHPC TYPE=ABEND, TERMINATE PGRM, TRANS, & TASK * 

ABCODE=YES USE ABCODE ALREADY SPECIFIED 

Note: The DFHPC macro will preserve the original contents of the two 
bytes starting at TCAPCTR by moving them to TCACCSV1. Thus a dump will 
contain the response codes from the last CICS/VS service call. If 
ABCODE (but not ABCODE=YES) is specified, the original contents of 
TCAPCAC will also be preserved in TCACCSV2. If ABCODE=YES is specified, 
and you wish the original contents of TCAPCAC to appear in the dump, 
they must be stored elsewhere before you store the ABEND code there. It 
is therefore preferable to use method 1 above when specifying a dump 
code . 
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Activate or Cancel an Exit for Abnormal Termination Processing (TYPE=SETXIT) 



The format of the DFHPC macro instruction to activate or cancel an exit 
to a user— written routine or program to be executed upon abnormal 
termination of a task is as follows: 




TYPE=SETXIT 

[ ,PROGRAM={name|YES] ]|[ ,ROOTINE={symbolic 

address | YES} ] 
[ ,NORESP=symbolic address] 
[ ,PGMIDER=symbolic address] 



This macro specifies that a user exit is to be: 

1. Activated, if the PROGRAM or ROUTINE operand is specified 

2. Canceled, if no additional operands are specified 

During abnormal termination of a task, a program— level ABEND exit 
facility is provided in CICS/VS program control so that a user— written 
exit routine can be executed if desired. One example of a function 
performed by such a routine is the "clean-up" of a program that has 
started but not completed normally. An ABEND exit within an application 
program is activated in response to the DFHPC TYPE=SETXIT macro 
instruction. The application programmer must specify the name of a 
program, or (for Assembler— language and COBOL programs) the address of a 
routine, to be given control when an abnormal termination condition 
occurs. The program name or routine address can be specified in the 
DFHPC TYPE=SETXIT macro, or placed in the appropriate field in the TCA 
before the macro is issued. A program name is placed in TCAPCPI; a 
routine address is placed in TCAPCERA. The PROGRAM and ROUTINE operands 
are mutually exclusive. 

A DFHPC TYPE=SETXIT macro instruction in which a program or routine 
name is specified overrides (effectively, replaces) any preceding DFHPC 
TYPE=SETXIT macro instruction in any application program at the same 
logical level. (Logical levels are illustrated in Figure 5.4—1.) Thus, 
each application program of a transaction can have its own exit, but 
only one exit at each logical level can be active. To cancel a 
previously established exit at the logical level of the application 
program in control, the application programmer can issue a DFHPC 
TYPE=SETXIT macro instruction in which neither the program name nor the 
routine name operand is specified* 

When a task ABEND occurs, CICS/VS searches for an active exit, 
starting at the logical level of the application program in which the 
ABEND occurred, and proceeding, if necessary, to successively higher 
levels. The first active exit found, if any, is given control. This 
procedure is shown in Figure 5.4—2, which also shows how subsequent 
ABEND exit processing is determined by the user^s exit routine or 
program. 
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Task ABEND 



Look at the 
next higher 



logical level 

A 



> 



\L 



Is there an exit 
active at this 
logical level? 



No 



No 



Is application 
program at the 
highest level? 



Yes 



V 




Terminate 




Link to program 


the task 




or branch to 
label 



RETURN 



V 



ABEND 



V 



I Action taken 
| in exit program 
j or routine 



Is application 
program at the 
highest level? 



No 



Exit to program 
at next higher 
logical level 



Yes 



Terminate 
the task 



Figure 5.4—2. ABEND Exit Processing 

Note ; When a DFHPC TYPE=XCTL macro is to be used to transfer control 
from an application program, there is a potential problem if an exit 
routine (rather than a program) has been specified within that 
application program, and the exit for the routine is still active when 
control is transferred. If, later, a short-on-storage condition occurs, 
the storage occupied by the application program may be re— used, and any 
attempt to refer to the re— used storage, as a result of a subsequent 
task ABEND, will have unpredictable results. This situation will not 
occur if an exit program is specified, instead of a routine. Routines 
can be used without risk in application programs that do not use a DFHPC 
TYPE=XCTL macro. 

To prevent recursive ABENDS in an exit routine, CICS/VS deactivates 
an exit upon entry to the exit routine. If attempting a retry of the 
operation, the programmer can branch to a point in the program that was 
in control at the time of the ABEND and issue the DFHPC TYPE=RESETXIT 
macro instruction to reactivate the exit* The user can also use this 
macro instruction to reactivate an exit that was canceled previously as 
described above. No additional parameters are required. 

Upon entry to an exit program, no addressability can be assumed other 
than that normally assumed for an application program coded in the 
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language. If the exit logic is in the form of a routine, the amount of 
addressability varies with the source language, as detailed under 
"Creating a Task ABEND Exit" in the CICS/VS System Programmer' s 
Reference Hanual . For additional information concerning preparation of 
the exit routine, see that manual. 

The following example shows how to establish a program as an exit: 

DFHPC TYPE=SETXIT,PROGRAM=EXITPGM 

The following examples show how to establish a program as an exit by 
dynamically storing the program name prior to executing the DFHPC 
TYPE=SETXIT macro instruction. 

For Assembler language : 

HVC TCAPCPI^CLe'EXITPGH" 

DFHPC TYPE=SETXIT,PROGRAM=YES 

F or COBOL : 

HOVE •EXITPGM 1 TO TCAPCPI. 

DFHPC TYPE=SETXIT,PROGRAM=YES 

F or PL/I : 

TCAPCPI=«EXITPGH»; 

DFHPC TYPE=SETXIT,PROGRAM=YES 

The following examples show how to establish a routine as an exit r>y 
dynamically storing the address of the routine prior to executing the 
DFHPC TYPE=SETXIT macro instruction. (Note that routines cannot be 
established as exits in PL/I application programs.) 

For Assembler language : 

LA 14,EXITRTN 
ST 14,TCAPCERA 

DFHPC TYPE=SETXIT,ROUTINE=YES 



For COBOL 



DFHPC TYPE=COBADDR,LABEL=EXITRTN 
HOVE TCAPCLA TO TCAPCERA . 



DFHPC TYPE=SETXIT,ROUTINE=YES 
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Reactivate an Exit for Abnormal Termination Processing (TYPE=RESETXIT) 



The format of the DFHPC macro instruction to reactivate an exit to a 
user— written routine or program to be executed upon abnormal termination 
of a transaction (task) is as follows: 



T 



| DFHPC | TYPE=RESETXIT | 

I I I 



.1 L. 



This macro specifies that an exit to user— written abnormal 
termination processing is to be reactivated after a preceding 
application program cancellation or CICS/VS cancellation upon execution 
of the exit routine. 
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Convert Symbolic Label to Address (TYPE = COB ADDR) 

The format of the DFHPC macro instruction to convert a symbolic label 
appearing in a COBOL program to an address is as follows: 



1 1 

I I 

DFHPC | TYPE=COBADDR | 

I ,LABEL=symbolic label | 



This macro specifies that the address of the location represented by 
a symbolic label is to be returned in TCAPCLA to the application 
program. The first byte of TCAPCLA can be non— zero, and should 
therefore be initialized if necessary. 

A comparable facility is availaDle within both PL/I and Assembler 
language; this macro instruction is designed to provide the capability 
for COBOL programmers. COBOL support must have been generated within 
CICS/VS to support COBOL programs* 
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Test Response to a Request for Program Services (TYPE = CHECK) 

The format of the DFHPC macro instruction to test the CICS/VS response 
to a reguest for program management services is as follows: 



DFHPC | TYPE=CHECK 

[ / NORESP=symbolic address] 
[ ,PGMIDER=symbolic address] 



Program Control Response Codes 



To test the response code the application programmer m 
CICS/VS response codes and their meanings, and (2) the 
which he can refer to the response code* If the Assem 
PL/I programmer elects to check for a particular respo 
pattern, he can access the response code at TCAPCTR . 
programmer who elects to check for a particular respon 
pattern can access the response code at TCAPCRC. The 
codes and the conditions to which they correspond are 
right— hand columns of Figure 5.4— 3. DFHPC macro instr 
the conditions are applicable are shown at the left. 



ust know (1) the 

symbolic label by 
bier— language or 
nse-code bit 
The COBOL 
se— code bit 
possible response 
identified in the 
uctions for which 



1 -■■- " - " ' 1 

I Program | | I 
| Services Reguest | | Response Code | 

1 hv DFHPP Hnfrn 1 1 - - . 1 


J Instruction | Condition | Assembler | COBOL | PL/I | 


| LINK, LOAD, i NORESP | X s 00 s | LOW-VALUES | 00000000| 
| SETXIT, CHECK | (Normal response) | | (PCARCNR) | | 

| LINK, LOAD, | PGMIDER | X»01» | 12-1-9 | 00000001| 
| SETXIT, CHECK | (Program identi- | | (PCPGMIDER)| | 
I I fication error) | | | | 


I Note: I 
| The names enclosed in parentheses in the COBOL column indicate | 
| the condition names generated by CICS/VS. These -names may be used | 
| in testing for the conditions in a COBOL program. | 



Figure 5.4—3. Program Control Response Codes 

Note : Because the multipunch codes to be checked in a COBOL program 
coraaonly correspond to unprintable characters, an alternative facility 
is provided in CICS/VS for use by the COBOL programmer. In COBOL the 
response code can be referred to by a condition name, formed as a two- 
character identification of the CICS/VS management module providing the 
reguested service, followed by the keyword for the condition being 
checked (for example, PCNORESP) . Ose of this approach is illustrated in 
the examples at the end of this discussion. 

To provide for the possibility of failure to find a reguested program 
in the processing program table (PPT) , or finding a disabled program in 
response to DFHPC TYPE=LINK or TYPE=LOAD, the COND operand must be 
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included in these macros. This operand causes control to be passed to 
the user— specified exception— handling routine specified in the PGHIDER 
operand if the error occurs. If the COND operand is not specified and 
the error occurs, the requesting program is abnormally terminated with 
an APCT ABEND code. 

The following examples show how to examine the response code provided 
by CICS/VS at TCAPCTR (for Assembler language or PL/I) or TCAPCRC (for 
COBOL) and transfer control to an appropriate user— written error- 
handling routine. The alternative approach available to COBOL 
programmers is also shown. 

F or Assembler language : 



NORMAL RESPONSE 



GOOD 



For COBOL 



DFHPC 


TYPE=SETXIT, 




PROGRAM=MYPROG 


CLI 


TCAPCTR, X»00» 


BE 


GOOD 


DFHPC 


TYPE=ABEND 


DS 


OH 



DFHPC TYPE=SETXIT, 

PROGRAM=MYPROG 
IF TCAPCRC = • • THEN GO TO GOOD. NOTE 12-0-1-8-9 NORESP. 
DFHPC TYPE=ABEND 



GOOD. 



Alternatively, the COBOL programmer may test responses by using the 
CICS/VS generated condition names. 

IF PCNORESP THEN GO TO GOOD. 



For PL/I : 

DFHPC TYPE=SETXIT, * 

PROGRAM=MYPROG 
IF TCAPCTR=»0 , B THEN GO TO GOOD; /* NORMAL RESPONSE */ 
DFHPC TYPE=ABEND 
GOOD: 
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Operands of DFHPC Macro 



ABCODE= 



indicates that main storage related to the transaction is to be 
dumped and provides a four— character abnormal termination code 
to identify the output dump. 

value 

is a combination of four alphabetic, numeric, and/or 
special characters to be printed as the abnormal 
termination code. 



YES 



indicates that the abnormal termination code has been 
placed in TCAPCAC. 



Note : If a dump is requested, any information in the common 
control area of the application program communication section 
of the TCft is likely to be different in the dump. The DFHPC 
TYPE=ABEND macro preserves the original contents of the 
overwritten fields in the TCA by moving the two bytes starting 
at TCAPCTE to TCACCSV1. If an explicit abnormal termination 
code is specified, the macro will also move the original 
contents of TCAPCAC to TCACCSV2. If ABCODE=YES is specified, 
and the original contents of TCAPCAC are required in the dump, 
the information must be stored elsewhere before storing an 
abnormal termination code there. If the ABCODE operand is not 
specified, the macro does not use the TCAPCAC field. 

CANCEL=YES 

indicates that all exits established by DFHPC TYPE=SETXIT macro 
instructions at any level in the task are to be canceled; in 
effect, they are ignored. 

COND=YES 

indicates that control is to be returned to the program issuing 
the macro instruction if the program specified in the PROGRAM 
operand cannot be found in the PPT or is disabled. If this 
operand is omitted and the requested program cannot be found or 
is disabled, the task is abnormally terminated with the ABEND 
code "APCT". 

LABEL=symbolic label 

is the symbolic label that represents the location in the COBOL 
program for which the address is required. 

LOADLST=NO 

indicates that the loaded module is not to be deleted when the 
task issuing the load request is terminated; that is, the 
loaded module remains resident until deleted at the request of 
this task or of another task. 

NORESP=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if no errors occur during program 
control processing. NORESP signifies "normal response." 
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PGMIDER=sy»abolic address 

specifies the entry label of the user-uritten routine to which 
control is to be passed if the requested program cannot be 
found in the PPT or is disabled. Control will not be passed 
unless the COND operand is specified also in the TYPE=LINR or 
TYPE=LOAD macros, or unless the PROGRAM operand is specified 
also in the TYPE=SETXIT macro. 

PROGRAM=name 

is the name of the program to which control is to be passed or 
the name of the program, table, or map to be loaded; if 
omitted, the name is assumed to be in TCAPCPI . TCAPCPI is an 
eight— character field; names less than eight characters must be 
padded right with blanks. If the requested program cannot be 
found or is disabled, the task is abnormally terminated with 
the ABEND code "APCT". 

For the TYPE=SETXIT macro only, PROGRAH=name specifies the 
name, in the PPT, of the program to receive control if abnormal 
termination occurs. PROGRAM=YES specifies that the name of the 
program to receive control has been placed in TCAPCPI. 

ROUTINE= 

identifies the routine to receive control if abnormal 
termination occurs. (This operand applies only to Assembler- 
language and COBOL programs.) 

There is a risk involved in the use of this operand if the 
application program transfers control using a DFHPC TYPE=XCTL 
macro. The occurrence of a short— on— storage condition could 
lead to the storage used by this application program being re- 
used, and any reference to the re— used storage would have 
unpredictable results. 

symbolic address 

is the symbolic address of the routine to receive control. 

YES 

indicates that the address of the routine to receive 
control has been placed in TCAPCERA. 

TRANSID=transaction code 

is the transaction identification to be used with the next 
input message entered from the terminal with which this 
requesting task has been associated prior to this request for 
return of control. 
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Storage management controls all main storage for CICS/VS and for user- 
written application programs^ Requests to acguire or release main 
storage are communicated to CICS/VS storage control by means of the 
storage management macro instruction (DFHSC) . 

CICS/VS management programs automatically issue reguests for main 
storage to provide input/output areas, program load areas, and user- 
defined work areas needed to process a task. An application program can 
also issue reguests for main storage to provide intermediate work areas 
and any other main storage area not automatically provided by CICS/VS 
but needed to process a task. Main storage acquired by an application 
program can be initialized to any bit configuration, for example, binary 
zeros or EBCDIC blanks. 

Main storage associated with a task is controlled and accounted for 
by CICS/VS. This allows CICS/VS to release all main storage associated 
with a task upon request or when the task is normally or abnormally 
terminated. Main storage is accounted for as follows: 

• Task control areas (TCAs) are accounted for through pointers in the 
dispatch control areas (DCAs) . The DCAs are chained from the 
common system area (CSA ) . 

• Task storage is chained off the task control area (TCA) . 

• Terminal storage is chained off the TCTTE (the TCTTESC field is the 
origin of the terminal input/output area (TIOA) chain; the TCTTEDA 
field contains the address of the curren t TIOA regardless of the 
position of that TIOA on the chain) . 

• Program storage is accounted for in the processing program table 
(PPT) . 

• Suspended tasks are accounted for by the suspending CICS/VS 
management program (task control, storage control, or temporary 
storage control). 

If there is insufficient main storage to satisfy a storage 
acquisition request, TCASCSA is filled with binary zeros. All activity 
within the task is suspended until sufficient dynamic storage becomes 
available and its address is placed in TCASCSA, unless the application 
programmer has specified in his request that control is to be returned 
to the application program. Lack of storage will cause a short-on— 
storage condition. The initiation of new tasks is restricted by CICS/VS 
until the short— on— storage condition is alleviated. Normally, this 
occurs as a result of some other task releasing storage currently 
reserved for it. (See "Declare a Task to be Purgeable" in Chapter 5.3., 
for corrective action that can be taken if the short— on— storage 
condition continues.) 
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Obtain and Initialize Main Storage (TYPE=GETMAIN) 



The format of the DFHSC macro instruction to obtain main storage and 
initialize the area obtained, if required, is as follows: 




DFHSC | TYPE=GETMAIN 

| [,INITIHG= {number | YES} ] 

| [ ,NUHBYTE=number] 

| [ ,COND={YES| (YES, symbolic addr) | (NO, symbolic addr)} ] 

| [ ,CLASS= {TERMINAL | USER | TRANSDATA |TEHPSTRG} ] 



This macro instruction is used to obtain main storage of a specified 
size and class and, optionally, to initialize that storage to a 
specified bit configuration. The address of the storage area obtained 
is placed in TCASCSA on a doubleword boundary by CICS/VS. TERMINAL, 
TRANSDATA, and TEMPSTRG can be abbreviated to TERM, TD, and TS 
respectively. 

When using this macro instruction, the application programmer should: 

© Check whether any existing storage that is no longer required by 
the task should be released, to avoid causing a short— on— storage 
condition to occur, or if it may be left for CICS/VS to release 
when the task is terminated. 

• Specify the class of storage required using the CLASS operand. 

o Calculate the number of bytes required and either specify that 
amount in the NUMBYTE operand, or place it in TCASCNB, in binary 
form, before issuing the DFHSC macro instruction. A zero data 
length is not allowed for a DFHSC TYPE=GETMAIN macro instruction. 

© Specify the COND operand if control is to be returned to the 

application program, irrespective of whether the requested storage 
has been acquired or not. 

o Specify a symbolic base address for the storage area. 

«> Hove the storage address located at TCASCSA to the symbolic oase 
address. (This address points to the storage accounting area of 
the storage area.) 

° Co Py the symbolic storage definition for the appropriate 

input/output area or storage accounting area p rio r to the symbolic 
definition of the user's program storage area. 

The following example shows how to request a 1024— byte area of main 
storage : 



DFHSC TYPE=GETMAIN, 
INITIHG=00, 
NUMBYTE=1024, 
CLASS=TERHINAL 



OBTAIN NEW STORAGE AREA 
INITIALIZE WITH BINARY ZEROS 
SIZE OF STORAGE REQUESTED 
CLASS OF STORAGE REQUESTED 



The following examples show how to specify the size of a required 
storage area and the value to which it is to be initialized and then 
reguest that the storaqe be acquired. 
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For Assembler lang uage : 



MVI 


TCASCIBjB'O 1 


MVC 


TCASCNB,=HM024 


DFHSC 


TYPE=GETMAIN, 




INITIMG=YES, 




COND=YES, 




CLASS=TERMINAL 


CLC 


TCASCSA, =F , 0» 


BE 


NOSTRG 


L 


TIOABAR, TCASCSA 


For COBOL: 





INITIALIZE WITH BINARY ZEROS 
SIZE OF STORAGE REQUESTED 



OBTAIN NEW STORAGE AREA 

INITIALIZE WITH BINARY ZEROS 

RETURN CONTROL 

CLASS OF STORAGE REQUESTED 

WAS STORAGE AVAILABLE? 

BRANCH IF NOT 

LOAD REGISTER IF STORAGE FOUND 



MOVE • » TO TCASCIB. 
MOVE 1024 TO TCASCNB. 



NOTE INITIALIZE WITH BLANKS 
NOTE SIZE OF STORAGE REQUESTED 



DFHSC TYPE=GETMAIN, 

INITIMG=YES, 

COND=YES, 

CLASS=TERMINAL 
IF TCASCSA EQUAL GO TO NOSTRG. 
MOVE TCASCSA TO TIOABAR. 



OBTAIN NEW STORAGE AREA 
INITIALIZE WITH BLANKS 
RETURN CONTROL 
CLASS OF STORAGE REQUESTED 



For PL/I : 



TCASCIB=0; 
TCASCNB=1024; 



/♦INITIALIZE WITH BINARY ZEROS*/ 
/♦SIZE OF STORAGE REQUESTED*/ 



DFHSC TYPE=GETMAIN, 
INITIMG=YES, 
COND=YES, 
CLASS=TERMINAL 



OBTAIN NEW STORAGE AREA 
INITIALIZE WITH BINARY ZEROS 
RETURN CONTROL 
CLASS OF STORAGE REQUESTED 



IF UNSPEC (TCASCSA) = THEN GO TO NOSTRG; 

TIOABAR=TCASCSA; /*LOAD REGISTER IF STORAGE FOUND*/ 
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Release Main Storage (TYPE=FREEMAIN) 

The format of the DFHSC macro instruction to release main storage is as 
follows: 



r '■ 

1 

1 

1 
i 


r r m ■ -■- - 

1 1 

| DFHSC | TYPE=FREEMAIN 

| | [ ,RELEASE=ALL] 
i i 




1 


1 1 
i i 


_ i 



If the task itself does not release acquired storage, the storage is 
released by CICS/VS upon termination of the task. 

When this macro instruction is used to release a single storage area, 
the address of that area must be placed in TCASCSA prior to execution of 
the macro instruction. If all terminal storage acquired by means of 
DFHSC TYPE=GETMAIN,CLASS=TERMINAL macro instructions in the application 
program or by CICS/VS on behalf of the task is to be released, the 
RELEASE=ALL operand will achieve that result; in this case, it is not 
necessary to place an address in TCASCSA i 

The following example shows how to release all main storage currently 
allocated to a terminal: 

DFHSC TYPE=FREEMAIN, 

RELEASE=ALL RELEASE ALL TERMINAL STORAGE 

The use of the RELEASE=ALL operand is restricted during basic mapping 
support (BMS) output operations having "OUT" disposition, to preserve 
the terminal storage used by BMS. Once a DFHBMS macro with "OUT" 
disposition has been issued, the application program must not issue a 
DFHSC TYPE=FREEMAIN,RELEASE=ALL macro until either a DFHBMS TYPE=PAGEOUT 
or DFHBMS TYPE=PURGE macro has been issued. 

The use of the RELEASE=ALL operand is also restricted during data 
interchange output operations (ADD, ERASE, REPLACE, NOTE, QUERY, END, 
and ABORT) to preserve the terminal storage used by the data interchange 
program (DFHDIP) • Once a destination has been selected, RELEASE=ALL 
must hot be specified until TYPE=END, TYPE=QUERY, or TYPE=ABORT has been 
specified in the DFHDI macro for that destination. 

The following examples show how to release a single main storage 
area, placing the address of the area to be released in TCASCSA before 
issuing the release request. 

F or Assembl er lang uage : 

ST TIOABAR, TCASCSA PLACE STORAGE AREA ADDRESS IN TCA 



DFHSC TYPE=FREEMAIN RELEASE STORAGE AREA 
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For COBOL : 

MOVE TIOABAR TO TCASCSA. NOTE PLACE STRG AREA ADDR IN TCA. 

DFHSC TYPE=FREEMAIN RELEASE STORAGE AREA 

F or PL/I : 

TCASCSA=TIOABAR; /*PLACE STORAGE AREA ADDRESS IN TCA*/ 

DFHSC TYPE=FREEMAIN RELEASE STORAGE AREA 
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Operands of DFHSC Macro 



CLASS= 



COND= 



specifies the class of the storage to be acquired, 



TERMINAL or TERM 

indicates that the storage area is to be used as a terminal 
input/output area (TIOA) , which is chained to the terminal 
control table terminal entry (TCTTE). All requests for 
storage related to terminal input/output must specify this 
class. 

If storage other than TERMINAL class is used as a TIOA for 
subsequent terminal control input /output operations, 
storage violations may occur. 

USER 

indicates that the storage area is to be associated with 
the application program and used by that program. This 
area is chained to the TCA associated with the requesting 
task. 



TRANSDATA or TD 

indicates that the storage area is to be used for transient 
data record storage (a TDIA or TDOA) . This area is chained 
to the TCA associated with the requesting task and is used 
by transient data control. 



TEMPSTRG or TS 

indicates that the storage area is to be used as a 
temporary storage input/output area (TSIOA) . This area is 
chained to the TCA associated with the requesting task and 
is used by temporary storage control. 

Note ; USER, TRANSDATA, and TEMPSTRG specifications have 
essentially the same effect. The advantage of using 
CLASS=TRANSDATA or CLASS=TEMPSTRG when either is appropriate is 
that the specification serves as documentation i>oth in the 
program and in the class code of the storage accounting field 
for the area. 



is an optional operand that ensures that control is returned to 
the application program, whether or not the reguested storage 
area is acquired. 

YES 

indicates that control is to be given to the instruction 
immediately following the macro expansion for the DFHSC 
TYPE=GETMAIN macro instruction in the application program. 
To determine whether the reguested storage area was 
acquired, the application proqram must examine TCASCSA, 
which is set to binary zeros if the request cannot be 
satisfied. 
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(YES, symbolic address) 

causas a branch to the location specified by the symbolic 
address if the reguested storage was acguired; otherwise , 
control is returned to the instruction immediately 
following the macro expansion for the DFHSC TYPE=GETMAIN 
macro instruction in the application program. 

(NO, symbolic address) 

causes a branch to the location specified by the symbolic 
address if the reguested storage was not acguired; 
otherwise, control is returned to the instruction 
immediately following the macro expansion for this macro 
instruction in the application program. 

INITIMG= 

is an optional operand that can be used to initialize the 
acguired storage area to the bit configuration desired. 

number 

is a two-digit hexadecimal numeral indicating the bit 
configuration desired. 

YES 

indicates that the desired bit configuration is in TCASCIB. 

NUHBYTE=nuraber 

is a decimal numeral up to 65520 (32767 when CLASS=TERMINAL) 
specifying the size, in bytes, of the storage area being 
reguested; if omitted, the number of bytes is assumed to be 
stored in binary form in TCASCNB. A zero data length is not 
allowed for a DFHSC TYPE=GETHAIN macro instruction. In BMS 
mapping operations, the number of bytes can be specified as an 
Assembler language expression, for example: 

N(JMBYTE=mapname . E-TIOADBA 

Note: Depending upon the class of storage specified (see the 
CLASS operand) , CICS/VS storage management automatically 
increments the amount of storage reguested to allow for the 
storage accounting field and other control information. For 
CLASS=USER and CLASS=TERHI1JAL (TIOA) storage, the exact number 
of bytes reguired should be specified. For CLAS3=TRANSDATA 

(TDIA and TDOA) and CLASS=TEHPSTRG (TSIOA) storage, the amount 
reguested must include four additional bytes to allow for a 
portion of CICS/VS control information, namely, the length 

(LLJrfJtf) field at the beginning of the area. (See also the 
section "Additional Guidelines" in Chapter 2.3 that apply when 
programming in COBOL.) 



Chapter 5.5. Storage Control (DFHSC Macro) 415 



RELEASE=ALL 

indicates that all main storage acquired by means of DFHSC 
TYPE=GETMAIN,CLASS=TERMINAL macro instructions is to be 
released. 

The use of the RELEASE=ALL operand is restricted during basic 
mapping support (BMS) output operations that have an OUT 
disposition; this restriction preserves the terminal storage 
used by BMS. Once a DFHBMS macro instruction with an OUT 
disposition has been issued, the application program must not 
issue a DFHSC TYPE=FREEMAIN,RELEASE=ALL macro instruction until 
either a DFHBMS TYPE=PAGEOUT or DFHBMS TYPE=PORGE macro 
instruction has been issued. 

If this operand is not specified, only one storage area can be 
released by a DFHSC TYPE=FREEMAIN macro instruction; the 
address of that area must be in TCASCSA and must be the main 
storage address returned as a result of a previously issued 
DFHSC TYPE=GETMAIN macro instruction. 
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Transient data management provides, through transient data control, a 
generalized queuing facility. Data can be queued (stored) for 
subsequent internal or external processing. Selected units of 
information, as specified by the application programmer, can be routed 
to or from predefined symbolic destinations, either intrapartition or 
extrapartition. The definitions for the destinations must be contained 
in a destination control table (DCT) established by the system 
programmer at system generation. 

Intrapartition destinations are queues of data on direct access 
storage devices developed for input to one or more programs running 
asynchronously (concurrently) as separate tasks; they are internal to 
the CICS/VS partition/region. Data directed to or from these internal 
destinations is called intrapartition data and must consist of variable- 
length records. Intrapartition destinations can be associated with 
either a terminal or an output data set. Intrapartition data may be 
ultimately transmitted upon request to a destination terminal or 
retrieved sequentially from the output data set. Typical uses of this 
facility involve message switching, broadcasting, data base access and 
routing of output to multiple terminals (for example, for order 
distribution), queuing of data (for example, for assignment of order 
numbers or priority by arrival) , and data collection (for example, for 
batched input from 2780 Data Transmission Terminals) . 

An intrapartition queue is reusaale. The system programmer can 
indicate, by symbolic destination, uhether (1) transient data space 
management is to control the reuse of tracks associated with a 
particular destination identification (DESTID) , or (2) the releasing of 
track space is to be controlled through use of the transient data PURGE 
macro instruction. If transient data space management is not used, an 
intrapartition queue continues to grow, irrespective of whether the data 
has been read, until the application programmer purges it. 

Extrapartition destinations are queues (data sets) external to the 
CICS/VS partition/region, residing on any sequential device (DASD, tape, 
printer, and so on). In general, sequential extrapartition destinations 
are used for storing data external to the CICS/VS partition/region or 
for retrieving data from outside the partition/region. For example, one 
task may read data from a remote terminal, edit the data, and write the 
results to a data set for subsequent processing in another 
partition/region. Logging data, statistics, and transaction error 
messages are examples of data that can be written to extrapartition 
destinations. In general, extrapartition data created by CICS/VS is 
intended for subsequent batched input to non-CICS/VS programs. Data can 
also be routed to an output device such as a line printer. 

Data directed to or from an external destination is called 
extrapartition data and consists of sequential records that are fixed— 
or variable— length , blocked or unblocked. The record format for a 
particular extrapartition destination must be described by the system 
programmer when setting up the destination control table (see the 
CICS/VS System Programmer's Reference Manual) . 

Intrapartition and extrapartition destinations can be used as 
indirect destinations, which are symbolic references to still other 
destinations. This facility provides some flexibility in program 
maintenance in that data can be routed to a destination known by a 
different symbolic name, without the necessity for recompiling existing 
programs that use the original name. Only the destination control table 
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need be changed. The application programs can route data to the 
destination using the previous symbolic name; however, the previous name 
is now an indirect destination that refers to the new symbolic name. 
Since indirect destinations are established by means of destination 
control table entries, the application programmer need not usually be 
concerned with how this is done. Further information is available in 
the C ICS/VS System Programmer 's Reference Manual . 

For intra part it ion destinations, CICS/VS provides the option of 
automatic task initiation. A basis for automatic task initiation is 
established by the system programmer by specifying a nonzero trigger 
level for a particular intrapartition destination in the DCT. (See the 
discussion of the DFHDCT TYPE=INTRA macro instruction in the CICS/VS 
System Programmer's Reference Manual .) When the number of entries (POTs 
from one or more programs) in the queue (destination) reaches the 
specified level, a transaction specified in the definition of the 
destination is automatically initiated. Control is passed to a program 
that processes the data in the queue; the program must issue repetitive 
GETs to deplete the queue. 

Once the queue has been depleted, a new automatic task initiation 
cycle begins. That is, a new task is scheduled for initiation when the 
specified trigger level is again reached, whether or not execution of 
the prior task has terminated. 

If an automatically initiated task does not deplete the gueue, access 
to the queue is not inhibited. The task may be normally or abnormally 
terminated before the queue is emptied (that is, before a QOEZERO 
response is returned in response to a DFHTD TYPE=GET macro instruction) . 
If the destination is a terminal, the same task is reinitiated 
regardless of the trigger level. If the destination is a data set, the 
task is not reinitiated until the specified trigger level is reached. 
If the trigger level of a queue is zero, no task is automatically 
initiated. To ensure that termination of an automatically initiated 
task occurs when the queue is empty, the application program should test 
for a QUEZERO condition rather than for some application— dependent 
factor such as an anticipated number of records. It is the QUEZERO 
condition only that indicates a depleted queue. 

Requests for transient data services are communicated to transient 
data control through CICS/VS macro instructions. Transient data control 
then executes as a service program under control of the TCA of the 
requesting program. It runs at the priority of the requesting program 
and saves and restores registers from its TCA. After the requested 
transient data service has been provided (or attempted) , control is 
returned to the next executable instruction in the requesting program. 

The transient data management macro instruction (DFHTD) is used to 
request any of the following services: 

1. Direct data to a predefined symbolic destination which references a 
data set or a terminal 

2. Acguire data from a predefined symbolic source which references a 
data set or a terminal 

3. Control the processing of an extrapartition data set 

4. Purge data associated with an intrapartition data set 

5. Check the response to a request for transient data services 

The application programmer must specify the parameters required when 
requesting transient data services. Parameters can be specified in two 
ways: (1) by including the parameters in operands of the DFHTD macro 
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instruction by which tha sarvica is requested, or (2) by coding 
instructions that move the required parameters to fields of the TCA 
p rior to issuing the DFHTD macro instruction. The latter approach 
provides some degree of flexibility in that a single DFHTD macro 
instruction can be tailored according to current logic needs within the 
application program. 

The application programmer can check the CICS/VS response to a 
request for transient data services as described under "Test Response to 
a Request for Transient Data Services," later in this chapter. The 
operands that can be specified in DFHTD macro instructions are explained 
in detail at tha and of the Chapter. 

CICS/VS routes a variety of messages generated by CICS/VS programs or 
tasks to transient data control. For example, terminal control detects 
a line or terminal problem (not related to a user— provided task) and 
routes control to the CICS/VS terminal abnormal condition program 
(DFHTACP) . DFHTACP then generates a message to the control system 
terminal log (CSTL) and/or to the control system master terminal (CSMT) . 

Destination definitions for all user and CICS/VS destinations must be 
included in the destination control table (DCT) . Lack of a destination 
definition leads to an IDERROR (identification error) response to a 
DFHTD macro instruction. 



Asynchronous Transaction Processing 

Typically, a task to be run under CICS/VS is initiated from a terminal 
and processed at regular intervals until completion, according to system 
service patterns established for CICS/VS. This mode of operation is 
sometimas referred to as sync hron ous transaction procassing, because the 
task has complete control of the terminal which initiated it. 

Support for asynchronou s transaction processing can also be generated 
into a CICS/VS system. This capability is designed primarily to permit 
a type of batch processing within CICS/VS. A task is initiated from a 
terminal as described above, but the specified transaction code causes a 
CICS/VS— provided asynchronous transaction processing program to read the 
data to an intrapartition data set. In effect, data collection from a 
device such as the 2780 Data Transmission Terminal is possible. When 
the data has been read, the device is freed for other activity. An 
application program processes the data, and, upon operator reguest, 
output is queued for subsequent transmission to a specified terminal. 
If the automatic task— initiation feature is generated into CICS/VS, that 
application program can be initiated automatically when a specified 
trigger level is reached (that is, when a specified number of inputs 
have been entered in the intrapartition data set) . 

The asynchronous transaction processing (ATP) facility is designed 
specifically for handling input from batch terminals like the 2780 and 
2770. Generally, ATP can also be used for other, interactive terminals 
like the 2741. However, ATP is not intended for, and will not support, 
input from the 2980, 3270, 3600 BTAH, 3735, or 3740; ATP is not 
available for VTAM logical units. Another consideration is that 
application programs intended to execute under control of ATP must not 
contain basic mapping support (BMS) macro instructions requesting BUS 
terminal paging facilities. 

Additional information concerning the creation of user exits for 
asynchronous transaction processing and the coding of the exit routines 
is given in the CI C S/VS System Programmer's Reference Manual . The 
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initiation of ATP by means of terminal commands is described in the 
CICS/VS Operator's Guide . 
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Dispose of Data (TYPE=PUT) 



The format of the DFHTD macro instruction to direct transient data to a 
predefined symbolic destination is as follows: 




TYPE=PUT 

[ ,DESTID=symbolic name] 
[ ,TDADDR=symbolic address] 
[ ,NORESP=symbolic address] 
[ ,IDERROR=symbolic address] 
[ ,IOERROR=symbolic address] 
[ ,NOTOPEN=symbolic address] 
[ ,NOSPACE=symbolic address] 



Destinations are intrapartition if associated with a facility 
allocated to the CICS/VS partition/region and extrapartition if the data 
is directed to some destination that is external to the CICS/VS 
partition/region. If intrapartition data is to be placed in the 
transient data output area, the symbolic storage definition for this 
area (DFHTDOA) should be copied in the application program. The first 
four bytes of this definition are a length field. All references to the 
output area should be made through the use of a register (TDOABAR) which 
points to the beginning of the area. 



The address of the output area contai 
must either be specified in the TDADDR o 
prior to issuing the macro instruction, 
intrapartition data, the first four byte 
contain the length of the record. For f 
of the output area must be the start of 
length field is LL##, where LL is a two- 
which includes the length of the data pi 
field) and ## should be two bytes contai 
data control does not release this area 
output . 



ning the data to be written, 
perand or placed in TCATDAA 

For variable— length records or 
s of the output area must 
ixed length records, the start 
the data. The format of the 
byte binary length (the value of 
us the four bytes for the length 
ning binary zeros. Transient 
after the data is written as 



If the destination is extrapartition, TYPEFLE=OUTPUT must be 
specified in the appropriate DFHDCT TYPE=SDSCI system macro, otherwise 
unpredictable results or an abnormal termination will occur. 

The following examples show how to write data to a predefined 
symbolic destination, in this case, the control system message log 
(CSHL) . The address of TDOAVRL, the four-byte length field at the 
beginning of the transient data output area (TDOA), is a pointer to the 
start of the variable— length data to be written. 



For Assembler language : 



TDOABAR 
DATA 



EQU 

COPY 

DS 



DFHTDOA 
CL10 



DFHSC 



L 

MVC 



TYPE=GETMAIN, 
CLASS=TRANSDATA, 
NUMBYTE=14 
TDOABAR, TCASCSA 
TDOAVRL, LENGTH 
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MVC DATA, MESSAGE 
MVC TCATDDI^C'CSML 1 
DFHTD TYPE=PUT, 

TDADDR=TDOAVRL 



F or COBOL ; 

02 TDOABAR PIC S9 (8) COMP 



01 DFHTDOA COPY DFHTDOA 
02 SDATA PIC X(10) . 



DFHSC TYPE=GETMAIN, * 

CLASS=TRANSDATA, * 

NUMBYTE=1U 

MOVE TCASCSA TO TDOABAR. 

MOVE SLENGTH TO TDOAVRL. \ 

MOVE SMBSSAGE TO SDATA. 

MOVE »CSML» TO TCATDDI. 

DFHTD TYPE=PUT, * 

TDADDR=TDOAVRL 



For PL/I ; 

^INCLUDE DFHTDOA; 

2 DATA CHAR (10) ; 



DFHSC TYPE=GETMAIN, * 

CLASS=TRANSDATA, * 

NUMBYTE=14 
TDOABAR=TCASCSA; 
TDOAVRL=LENGTH; 
DATA=MESSAGE; 
TCATDDI=»CSML»; 

DFHTD TYPE=PUT, * 

TDADDR=TDOAVRL 
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Acquire Queued Data (TYPE = GET) 



The format of the DFHTD macro instruction to retrieve gueued data from 
an extrapartition or intrapartition destination is shown below. The 
address of the retrieved data is returned at TCATDAA. 




TYPE=GET 
[ ,DESTID=s 
[ ,QUEBUSY= 
[ ,NORESP=s 
[ ,QUEZERO= 
[ ,IDERROR= 
[,IOERROR= 
[ ,NOTOPEN= 



ymbolic name] 
symbolic address] 
ymbolic address] 
symbolic address] 
symbolic address] 
symbolic address] 
symbolic address ] 



If the data is extrapartition, TCATDAA points to the first word of 
the data area. For variable— length records, the first four bytes of 
this area contain the length (LL^JJtf) as specified for variable— length 
data sets. TYPEFLE=INPUT or TYPEFLE=RDBACK must be specified in the 
appropriate DFHDCT TYPE=SDSCI system macro, and DESTID must not indicate 
a system spool file, otherwise unpredictable results or an abnormal 
termination will occur. 

If the data is intrapartition, the symbolic storage definition for 
the transient data input area (DFHTDIA) must have been copied in the 
application program. TCATDAA points to a CICS/VS input area defined by 
DFHTDIA. TDIAIRL contains the length (data length plus the length of 
the length field) of the area. 

Transient data (either intrapartition or extrapartition) must be 
moved from the input area before it can be used in any other 
input/output operation. 

If the application programmer issues a DFHTD TYPE=GET macro 
instruction, the input area acguired for the previous GET is reused if 
it is long enough to contain the input record. If it is not, CICS/VS 
acguires a new input area of sufficient length and releases the input 
area previously used. If the application programmer issues a DFHTD 
TYPE=PUT macro instruction, the input area acguired for a previous GET 
may also be changed or released. The application programmer should 
always move data to be saved from the input area to a user area to 
ensure that it is not overlaid with new data. Addressability to the 
area should also be reestablished following each GET. 

The application programmer should not attempt to free storage 
acguired by the transient data control program in response to a DFHTD 
TYPE=GET macro instruction. This storage is freed by CICS/VS in the 
case of intrapartition data, or by the operating system in the case of 
extrapartition data. An attempt to free storage acguired for 
extrapartition data may result in an abnormal termination of CICS/VS, 
since the storage area address returned by transient data control points 
to storage that is not part of the CICS/VS dynamic storage subpool. 

The following examples show how to read a variable— length record from 
an intrapartition data set specified prior to issuing the DFHTD TYPE=GET 
macro instruction. In these examples, the data set is the control 
system message log (CSHL) . 
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F or Assembler language : 

TDIABAR EQU 7 

COPY DFHTDIA 



MVC TCATDDI,=C»CSML« 

DFHTD TYPE=GET 

L TDIABAR, TCATDAA 



For _CO BOL : 

02 TDIABAR PIC S9 (8) COMP, 

01 DFHTDIA COPY DFHTDIA. 



HOVE »CSML» TO TCATDDI. 

DFHTD TYPE=GET 
MOVE TCATDAA TO TDIABAR 



For PL/I: 



^INCLUDE DFHTDIA; 

2 DUMMY CHAR (1) ; 



TCATDDI=»CSKL»; 
DFHTD TYPE=GET 
TDIABAR=TCATDAA; 



Assume that, in the above examples, the variable— length record is 
read from an extrapartition data set . The address placed at TCATDAA by 
CICS/VS is the address of the length (LL##) field that precedes the 
actual data. Since the DFHTDIA symbolic storage definition is being 
used, the address must be adjusted to point to the CICS/VS system 
section preceding the actual data* Therefore, an instruction to adjust 
the address should be inserted immediately following the instruction 
that moves the contents of TCATDAA to TDIABAR. The following examples 
apply to CICS/OS/VS but are applicable to CICS/DOS/VS if 'SS' is 
replaced by •8 I . 

F or Assembler languag e : 
SH TDIABAR, =H • 36 • 
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For COBOL: 

SUBTRACT 36 FROM TDIABAR. 



For PL/I : 



DCL TDIABAA FIXED BIN (31) BASED (TDIABAB) ; 
TDIABAB=ADDR (TDIABAR) ; /* OVERLAY POINTER */ 

TDIABAA=TDIABAA-36 /» DO POINTER ARITHMETIC */ 



Since these examples deal with variable— length records, the first 
byte of the data is assumed to be the length field (LLpp) . If the 
examples dealt with fixed— length records, appropriate values would be 40 
and 12 for CICS/OS/VS and CICS/DOS/VS, respectively. 

Note : These values are subject to change in future versions of CICS/VS, 
because this DSECT is intended only for intrapartition data sets. No 
DSECT is provided for extrapartition data. Each user should define the 
extrapartition DSECT so as not to use the absolute values in the above 
example. 
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Force End of Volume on an Extrapartition Data Set (TYPE=FEOV) 

The format of the DFHTD macro instruction to create a "forced end of 
volume" situation on an extrapartition magnetic tape data set is as 
follows: 




DFHTD | TYPE=FEOV 

I [ / DESTID=symbolic name] 

| [ / NORESP=symbolic address] 

I [ ,IDERROR=symbolic address] 

| [ , NOTOPEN=symbolic address] 



This macro specifies that a magnetic tape reel is to be rewound and 
unloaded; output labels are to be created as required and new input 
labels verified according to host operating system forced— and— of —volume 
processing. CICS/VS operation is halted, and the next tape reel must be 
loaded before CICS/VS operation is resumed. 

N ote ; This facility should be used with caution, since CICS/VS 
operation is halted until the new tape reel has been loaded. 

The following examples show how to create a "forced end of volume" 
situation on an extrapartition magnetic tape data set. 



For A ssembler language : 



MVC TCATDDI,=C»CSML» 
DFHTD TYPE=FEOV 



For COBOL; 



MOVE •CSML* TO TCATDDI 
DFHTD TYPE=FEOV 



For PL/I ; 



TCATDDI=»CSML»; 
DFHTD TYPE=FEOV 
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Purge Intrapartition Data (TYPE=PURGE) 



The format of the DFHTD macro instruction to purge all data associated 
with a particular intrapartition destination (queue) is as follows: 




DFHTD | TYPE=PURGE 

| [ ,DESTID=symbolic name] 

| [ ,NORESP=symbolic address] 

| [ , IDERROR=syrabolic address] 
I 



When transient data associated with a particular intrapartition 
destination (queue) is no longer needed, the application programmer can 
purge the data associated with that destination by issuing this macro 
instruction, which causes all storage associated with the destination to 
be freed (deallocated) .. 

This macro instruction must be used to free storage associated with a 
destination designated as nonreusable in the destination control table. 
Otherwise, the storage remains allocated to the destination; the data 
and amount of storage associated with the destination continue to grow 
whenever a DFHTD TYPE=PUT macro instruction refers to the destination. 
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Test Response to a Request for Transient Data Services (TYPE = CHECK) 



The format of the DFHTD macro instruction to test the CICS/VS response 
to a request for transient data services is as follows: 



r ■ ' ' ■ 






■ l 


i 


DFHTD 


TYPE=CHECK 

[ , NORESP=symbolic address] 
[ ,QUEZERO=symbolic address] 
[ ,IDERROR=symbolic address] 
[ ,IOERROR=symbolic address] 
[ ,NOTOPEN=symbolic address] 
[ ,NOSPACE=symbolic address] 

, ._.. , 


• 



Transient Data Response Codes 



The Assembler— language or PL/I programmer accesses transient data 
response codes at TCATDTR; the COBOL programmer accesses these response 
codes at TCATDRC. In addition, the COBOL programmer can refer to the 
response codes by means of condition names (for example, TDNORESP, 
TDQUEZERO etc.) . The possible response codes and their meanings are 
shown in Figure 5.6—1. 

If the application programmer does not check for a particular 
response to a service request, and the exception condition corresponding 
to that response occurs, program flow proceeds to the next seguential 
instruction in the application program. 
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Transient Data 
Request by 
DFHTD Macro 
Instruction 


Condition 


B 


lesponse Code | 


Assembler | 


COBOL | PL /I | 


ALL 


| NORESP 

(Normal response) 


X'OO 1 | 


LOU-VALUES | 00000000 | 
(TDNORESP) | | 


GET, CHECK 


QUEZERO 
(Queue is zero) 


X«01 B 


12-1-9 | 000000011 
(TDQUEZERO) | | 


ALL 


IDERROR 
(Identification 
I error) 


X«02» 


12-2-9 | 000000101 
(TDIDERROR)I 1 


PUT, GET, CHECK 


lOERROR 
(Input/Output 
error) 


X«04» 


12-4-9 | 000001001 
(TDIOERROR)| | 


PUT,GET,FEOV, 
CHECK 


NOTOPEN 
(Journal not open) 


X»08» 


12-8-9 | 000010001 
(TDNOTOPEN) | | 


POT, CHECK 


NOSPACE 
(No space on 
intrapartition 
gueue, or write 
not serviceable) 


X«10» 


12-11-1-8-9| 00010000| 
(TDNOSPACE)I | 


Note; | 
The names enclosed in parentheses in the COBOL column indicate | 
the condition names generated by CICS/VS. These names may be | 
used in testing for the respective conditions in a COBOL program. | 



Figure 5.6—1. Transient Data Control Response Codes 

The following examples show how to examine the response code provided 
by CICS/VS and transfer control to the appropriate user— written 
exception— handling routine. 



F or Assembler language : 



DFHTD TYPE=GET, 

DESTID=CSML 
CLI TCATDTR,X»00« 
BE GOOD 

DFHPC TYPE=ABEND,ABCODE=GETE 
GOOD DS OH 



NORMAL RESPONSE 
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For COBOL : 



DFHTD TYPE=GET, 

DESTID=CSML 
IF TCATDRC = • • THEN GO TO GOOD^ NOTE 12-0-1-8-9 NORESP. 
DFHPC TYPE=ABEND,ABCODE=GETE 



GOOD. 



Alternatively, the COBOL programmer may test responses by using the 
CICS/VS generated condition names. 

IF TDNORESP THEN GO TO GOOD. 



For PL/I ; 

DFHTD TYPE=GET, 

DESTID=CSML 
IF TCATDTR=»0»B THEN GO TO GOOD; /* NORMAL RESPONSE */ 
DFHPC TYPE=ABEND,ABCODE=GETE 
GOOD: 
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Operands of DFHTD Macro 

DESTID=symbolic name 

specifies the symbolic name of the destination to which the 
data is to be routed and queued, or from which queued data is 
to be read. This name must appear in the destination control 
table (DCT) . If this operand is omitted, the symbolic name of 
the destination is assumed to be in TCATDDI. For a TYPE=GET 
macro, DESTID must not indicate a system spool file. 

IDERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the symbolic destination referred to 
by a DFHTD macro instruction cannot be found. 

IOERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an input/output error occurs on a 
data record and the data record in error is skipped. Transient 
data returns an IOERROR indication as long as the queue can be 
read; a QUEZERO response is returned when the queue cannot be 
read, in which case, the user may attempt a restart. This 
condition can also be raised if an attempt is made to write a 
zero length record to an intrapartition data set. This 
condition can also be raised under VSAM if the record is too 
large to fit in a control interval. 

NORESP=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if no error occurs during a data set 
(file) operation. NORESP signifies "normal response." 

NOSPACE=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if no more space exists on a particular 
intrapartition queue or if the write request cannot be 
serviced. If the NOSPACE response is received, no more data 
should be written to the queue, because it may be lost. 

NOTOPEN=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if a destination is closed. 

QUEBUSY=symbolic address 

specifies the symbolic address of the routine to receive 
control if the input request attempts to access a record on an 
input intrapartition queue that has been enqueued upon for 
output by a PUT or PURGE request* If this operand is omitted, 
the task issuing the request waits until the queue is no longer 
being used for output. 

QUEZERO=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed when the destination (queue) accessed 
by a DFHTD TYPE=GET macro instruction is empty. 
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TDADDR=symbolic address 

specifies the symbolic address of the output area containing 
data to be written (for intrapartition data and variable— length 
extrapartition data, the first four bytes of this area must 
contain the length of the record) . If this operand is omitted, 
the address of the output area is assumed to be in TCATDAA. 
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Chapter 5.7. Temporary Storage Control (DFHTS Macro) 



Temporary storage control enables user -written application programs to 
store temporary data in main storage or in auxiliary storage on a direct 
access storage device. 

Temporary data is stored, retrieved, and released using a symbolic 
name (up to eight characters) assigned to the data by the originating 
| task. (The symbolic name must not consist solely of binary zeros.) 

| The data may be a single record or records retrieved from or added to 
a temporary storage message set. The former provides a typical "scratch 
pad" facility. The latter is designed primarily for terminal paging. 
It is used in conjunction with basic mapping support (see Chapter 4.3) 
and page supervision programs to achieve random access to general- 
purpose storage files. In general, the paging facility of temporary 
storage should be used only when multiple records are involved and 
random access to those records is necessary. This queuing of message 
sets should not be used for sequential data. Transient data management 
provides facilities for efficient handling of sequential data sets. If 
data contained in a message set is to be updated and retrieved by 
multiple tasks, it may be necessary to protect it by means of the task 
control enqueuing facility. 

Data placed in temporary storage can remain intact beyond the time 
that the originating task is active in the system. That is, even after 
the originating task is terminated and its transaction storage released, 
data placed in temporary storage can be accessed by other tasks through 
references to the symbolic name under which it was stored. Temporary 
data remains intact until released by the originating task or by any 
other task. Prior to release, it can be accessed any number of times. 

When temporary data is released, the space that it occupied is 
reusable. If the data was in main storage, the storage area becomes 
part of available dynamic storage. If the data was on auxiliary 
storage, the physical space that the data occupied becomes available and 
can be reused for other data^ 

Temporary data can be retrieved by the originating task or by any 
other task using the symbolic name assigned to it. The name assigned to 
I a single record should be unique. If more than one record has the same 
| name, the record is queued in temporary storage. If an attempt is made 
| to retrieve a record from the queue, the records will De presented on a 
I first in first out basis. All information moved to or from a temporary 
storage message set is referred to by a unique name assigned to the 
message set. Specific entries (logical records) within a message set 
are referred to by relative position numbers. To avoid conflicts caused 
by duplicate names, a naming convention should be established and 
followed by all programmers. For example, the operator identification, 
terminal identification, or transaction identification could be appended 
as a prefix or suffix to each programmer— supplied symbolic name. 

Temporary data can be stored in either main or auxiliary storage. 
Generally, main storage should be used if the data is needed for only 
short periods of time; auxiliary storage should be used if the data must 
oe kept for extended periods of time. Another consideration is that 
data stored on auxiliary storage is maintained after CICS/VS termination 
and can be recovered in a subsequent restart. No attempt is made to 
recover data in main storage. Main storage might be used to pass data 
from task to task or for unique storage that allows programs to meet the 
requirement of CICS/VS that they be quasi— reenterable. 
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Some uses of the page queuing facility follow: 

1. Terminal paging* A task could retrieve a large master record from 
a direct access data set, format it into several screen images, 
store the screen images temporarily in auxiliary storage, and then 
ask the terminal operator which "page" (screen image) is desired. 
The application programmer can provide coding (as a generalized 
routine or unique to a single application) to advance page by page, 
advance or back up a relative number of pages, and the like. This 
facility is provided by CICS/VS Basic Mapping Support as described 
in Chapter 4.3. 

2* A suspend data set. Assume a data collection task is in progress 
on a certain terminal. The task reads in one or more units of 
input and then allows the terminal operator to interrupt the 
process. If no interruption occurs (some kind of coded input), the 
task repeats the data collection process. If the operator 
interrupts the data collection stream with coded input, the data 
collection task writes its "incomplete" data to temporary storage 
and terminates the task. The terminal is now free for entry of a 
different transaction (perhaps a high— priority inquiry) . When the 
terminal is available to continue the data collection operation, 
the operator initiates the task in a "resume" mode, causing the 
task to recall its suspended data from temporary storage and 
continue as though it had not been interrupted. 

3. An application that accepts input data to be written as output on a 
preprinted form. 

The DFHTS macro is used to: 

• Acquire data from main or auxiliary storage 

• Send data to main or auxiliary storage 

© Update data in main or auxiliary storage 

• Release temporary data in main or auxiliary storage 

• Check the response to a reguest for temporary storage services 
Parameters can be specified in either of two ways: 

• By including the parameters in operands of the DFHTS macro 
instruction by which temporary storage services are requested, or 

• By coding instructions that place the parameter values in fields of 
the TCA prior to issuing the DFHTS macro instruction 

The second of these approaches provides flexibility in that the 
parameters of a single DFHTS macro instruction can vary to meet the 
logic needs of the application program. 

The CICS/VS response to a request for temporary storage services can 
be checked, as explained under "Test Response to a Request for Temporary 
Storage Services," later in this chapter. If the programmer does not 
check for a particular response, and the condition corresponding to that 
response occurs, program flow proceeds to the next sequential 
instruction in the application program. All operands that can be 
included in the DFHTS macro instruction are discussed at the end of the 
chapter. 
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Store Temporary Data as a Single Unit of Information (TYPE = PUT) 



The format of the DFHTS macro instruction to store a single unit of 
information as temporary data in main or auxiliary storage (that is, as 
though using a "scratch pad") is as follows: 




TYPE=PUT 

[ ,TYPOPER=REPLACE ] 

[ ,DATAID=name] 

[ ,TSDADDR= {symbolic address| YES} ] 

[ ,STORFAC= (AUXILIARY 1 MAIN) ] 

[ ,COND=YES ] 

[ ,NOSPACE=symbolic address 

[ , NORESP=symbolic address] 

[ ,IOERROR=symbolic address] 

[ ,INVREQ=symb'olic address] 

[ ,ERROR=symbolic address] 



This macro causes data to be written to temporary storage as a single 
unit of information (logical record) . 



Temporary data may be written from a t 
area (TSIOA) or from a main storage area 
programmer. It must have the standard va 
data length specified in the first four b 
contain LL&tf, where LL is a two— byte bina 
which includes the length of the data plu 
field) and JJ# is a two-byte field of bina 
temporary storage record size is based on 
characteristics. (See temporary storage 
Program mer's Guide or CIC5/D0S/VS Sys tem 



emporary storage input/output 
identified by the application 
riable— length format, with the 
ytes. These bytes should 
ry length field (the value of 
s the four bytes for the length 
ry zeros. The maximum 

user— specif ied data set 
in the CICS/OS/VS Syste m 
Programmer's Guide . ) 



Existing temporary storage data can be updated by adding the 
TYPOPER=REPLACE operand. This causes the current data identified by the 
DATAID operand to be released and replaced with the data provided. If 
the data cannot be found, the TYPOPER=REPLACE operand is ignored. 

The following examples show how to write a single record of 
information to temporary storage. 



F or Assembler language : 

TSIOABAR EQU 7 

COPY DFHTSIOA 
DATA DS CL11 



DFHSC TYPE=GETMAIN, 

CLASS=TEMPSTRG, 
NUMBYTE=15 
L TSIOABAR, TCASCSA 

MVC TSIOAVRL, LENGTH 
MVC DATA, MESSAGE 
DFHTS TYPE=PUT, 

DATAID=UNIQNME, 
TSDADDR=TSIOAVRL 
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LENGTH DC AL2 (L» HESSAGE+4 ) 
MESSAGE DC C'HELLO THERE 1 



For COBOL: 



WORKING-STORAGE SECTION. 

77 SMESSAGE PIC X(11) VALUE 'HELLO THERE* 

77 SLENGTH PIC 9 (8) COHP VALUE 15 

LINKAGE SECTION. 

02 TSIOABAR PIC S9 (8) COMP . 



01 DFHTSIOA COPY DFHTSIOA. 
02 SDATA PIC X(11) . 



DFHSC TYPE=GETMAIN, * 

CLASS=TEMPSTRG, * 

NUMBYTE=15 
HOVE TCASCSA TO TSIOABAR. 
MOVE SLENGTH TO TSIOAVRL > 
HOVE SMESSAGE TO SDATA. 
DFHTS TYPE=PUT, * 

DATAID=UNIQNME, * 

TSDADDR=TSIOAVRL 



F or PL/I : 



55INCLUDE DFHTSIOA; 

2 DATA CHAR (11) ; 



DFHSC TYPE=GETMAIN, * 

CLASS=TEMPSTRG, * 

NUHBYTE=15 
TSIOABAR=TCASCSA; 
TSIOAVRL= LENGTH? 
DATA=MESSAGE; 
DFHTS TYPE=PUT, * 

DATAID=UHIQNME, * 

TSDADDR=TSIOAVRL 
DCL MESSAGE CHAR (11) INIT («HELLO THERE 1 ); 
DCL LENGTH FIXED BIN (15) INIT (15) ; 
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Store Data to a Temporary Storage Message Set (TYPE=PUTQ) 

The format of the DFHTS macro instruction to cause an entry to be 
written to a temporary storage message set is as follows: 




TYPE=PUTQ 

[ ,TYPOPER=REPLACE] 

[ ,DATAID=name] 

[ ,TSDADDR= {symbolic address | YES) ] 

[ , STORFAC= ( AUXILIAR Y IHAIN1 ] 

[ ,EHTRY={ll|YES} ] 

[ ,COND=YES] 

[ ,NOSPACE=symi)olic address] 

[ ,NORESP=symbolic address] 

[ ,IOERROR=symbolic address] 

[ ,INVREQ=syrabolic address] 

[ ,ENERROR=symbolic address] 

[ ,ERROR=symbolic address] 



This macro causes a unit of information to be written to a message 
set, or gueue, in temporary storage. The unit is written in a relative 
position that is one beyond the last entry written to the message set. 
Following a PUTQ reguest, the relative record number is returned to the 
user in TCATSRN, a two-byte field. 

Temporary data may be written from a temporary storage input/output 
area (TSIOA) or from a main storage area identified by the application 
programmer. It must have the standard variable— length format, with the 
data length specified in the first four bytes ± These bytes should 
contain LLXP, where LL is a two— byte binary length field (the value of 
which includes the length of the data plus the four bytes for the length 
field) and )5)5 is a two— byte field of binary zeros. The maximum 
temporary storage record size is based on user— specif ied data set 
characteristics. (See temporary storage in the C ICS/VS System 
P rogrammer's Guides . ) 

Existing temporary storage data can be updated by specifying the 
TYPOPER=REPLACE and ENTRY operands. The specified record within the 
message set is released and replaced with the data provided. If the 
| data cannot be found an invalid entry number error occurs, and the 
TYPOPER=REPLACE and ENTRY operands are ignored. 
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Retrieve a Single Unit of Temporary Data (TYPE = GET) 

The format of the DFHTS macro instruction to retrieve a single unit of 
temporary data is as follows: 




TYPE=GBT 

[ ,STORCLS= {"TERMINAL I TERM I TEMPSTRG I TS 1 ] 

[ ,DATAID=name ] 

[ , TSDADDR= (symbolic address | YES} ] 

[ ,RELEASE={YES||K)} ] 

[ ,NORESP=symbolic address] 

[ ,IDERROR=symbolic address] 

[ ,IOERROR=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,ERROR=symbolic address ] 



This macro instruction causes a single record to be retrieved from 
temporary storage. A record stored in temporary storage by a DFHTS 
TYPE=PUT macro can be retrieved only by this macro instruction. A 
record, once retrieved, can be released by the RELEASE=YES operand. If 
RELEASE=NO is specified, or is assumed by default, the record is 
retained until released by another task or when CICS/VS is terminated. 

The STORCLS and TSDADDR operands are mutually exclusive. 

| If the TSDADDR operand is specified, the record, including its length 
field (LLJJJJ) , is placed either in storage at the symbolic address 
specified, or at the address in TCATSDA if YES is specified. 

| If STORCLS=TEMPSTRG is specified, the record, including its length 
field (LL#>J) , is placed in a temporary storage class storage area whose 
address is returned in TCATSDA. Before this area can be used as a 
| TSIOA, the application program must reduce the address in TCATSDA by 
| eight bytes to include the storage accounting area. This makes it 
addressable by TSIOABAR. 

| If STORCLS=TERMINAL is specified, the record, including its length 

| field (LLfttf) , is placed in a terminal class storage area. This area is 

I prefixed by CICS/Vs with an 8 byte storage area. The address of the 

| prefixed area is returned in TCftTSDA. 

If neither STORCLS nor TSADDR is specified, STORCLS=TEMPSTRG is 
assumed by default and processing is as described above. 

The following examples show how to read a single record from 
temporary storage with the required addressability and adjustments. The 
examples show the use of the DFHTS TYPE=GET macro with STORCLS =TEMPSTRG 
assumed by default. 
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For Ass embler lang uage : 

TSIOABAE EQO 7 

COPY DFHTSIOA 



DFHTS TYPE=GET / 

DATAID=UNIQNME 
L TSIOABAR,TCATSDA 
SH TSIOABAR^H^ 1 



For COBOL : 

02 TSIOABAR PIC S9 (8) COMP, 

01 DFHTSIOA COPY DFHTSIOA. 



DFHTS TYPE=GET, 

DATAID=UNIQNME 
MOVE TCATSDA TO TSIOABAR. 
SUBTRACT 8 FROM TSIOABAR. 



For PL/I : 



^INCLUDE DFHTSIOA; 

2 DATA CHAR (10) ; 



DFHTS TYPE=GET, 

DATAID=UNIQNME 
DCL TSIOBAA FIXED BIN (30) BASED (TSIOBAQ) ; 
TSIOABAR=TCATSDA ; 
TSIOBAB=ADDR (TSIOABAR) ; 
TSIOBAA=TSIOBAA-8; 



The following examples show tne use of the DFHTS TYPE=*GIT ftacro with 
STORCLAS=TERMINAL specified explicitly. 

For Assemble r language : 

TIOABAR EQU 7 

COPY DFHTIOA 



DFHTS TYPE=GET, * 

STORCLS=TERM, * 

DATAID=UNIQNME 

L TIOABAR , TCATSDA 
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For COBOL: 

02 TIOABAR PIC S9 (8) COMP* 

01 DFHTIOA COPY DFHTIOA 



DFHTS TYPE=GET, * 

STORCLS=TERM, * 

DATAID=UNIQNME 

MOVE TCATSDA TO TIOABAR. 



For PL/I ; 



^INCLUDE DFHTIOA; 

2 DATA CHAR (10) ; 



DFHTS TYPE=GET, * 

STORCLS=TERM, * 

DATAID=HNIQNME 
TIOABAR=TCATSDa; 
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Retrieve Data from a Temporary Storage Message Set (TYPE=GETQ) 

The format of the DFHTS macro instruction to retrieve a logical record 
from a temporary storage message set is as follows: 




TYPE=GETQ 

[ ,STORCLS= {TERMINAL I TEMPSTRG 1 ] 

[ ,DATAID=name ] 

[ ,TSDADDR = {symbolic address|YES} ] 

[,ENTRY={n|YES} ] 

[ / NORESP=symbolic address] 

[ ,IDERROR=symbolic address] 

[ ,IOERROR=symt>olic address] 

[ ,INVREQ=symbolic address] 

[ ,ENERROR=symbolic address] 

[ , ERROR=symbolic address] 



This macro causes an entry previously written to a temporary storage 
message set, or gueue, to be retrieved. A record stored in temporary 
storage by a DFHTS TYPE=PUTQ macro can only be retrieved by a TYPE=GETQ 
macro. The record to be retrieved from a gueue is identified by the 
ENTRY operand which indicates its relative position within the queues 
The position of an entry is determined by its order of creation. 
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Release a Single Unit of Temporary Data (TYPE = RELEASE) 

The format of the DPHTS macro instruction to release a single unit of 
data placed in temporary storage by means of a DFHTS TYPE=PUT macro 
instruction is as follows: 




TYPE=RELEASE 

[ , DATAID=name ] 

[ ,NORESP=symbolic address] 

[ ,IDERROR=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,ERROR=symbolic address] 



This macro causes the main or auxiliary storage area used for a 
single record of temporary data (created by means of a DFHTS TYPE=PUT 
macro instruction) to be released. 

If temporary data named in a DFHTS TYPE=RELEASE macro instruction is 
in main storage, the area that it occupies is released and returned to 
the available dynamic storage area. If the data is in auxiliary 
storage, the space is made available for reuse. 

A single unit of data should be released at the earliest possible 
time to avoid using excessive amounts of storage for this purpose. 

The following examples show how to release a single record from 
temporary storage. 



For Assembler language : 

KVC TCATSDI,=C 8 UNIQNME B 
DFHTS TYPE=RELEASE 



For COBOL : 

MOVE •UNIQNME 1 TO TCATSDI, 
DFHTS TYPE=BELEASE 



For PL/I : 



TCATSDI= , DNIQNME»; 
DFHTS TYPE=RELEASE 
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Purge a Temporary Storage Message Set (TYPE=PURGE) 

The format of the DFHTS macro instruction to purge, or free, data saved 
as a temporary storage message set (that is, in response to DFHTS 
TYPE=PUTQ macro instructions) is as follows: 




TYPE= PURGE 

[ ,DATAID=name] 

[ ,NORESP=symbolic address] 

[ ,IDERROR=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,ERROR=symbolic address] 



This macro causes all existing entries in a temporary storage gueue 
(created by means of DFHTS TYPE=POTQ macro instructions) to be freed. 
There is no way to free selected records froa a temporary storage 
message set; in particular, a DFHTS TYPE=RELEASE macro instruction 
cannot be used to free a record that is part of a message set created by 
means of DFHTS TYPE=PUTQ. 

If the temporary data is in main storage, the area that it occupies 
is freed and returned to the available dynamic storage area. If the 
data is in auxiliary storage, the space is made available for reuse. 

A temporary storage message set should be purged at the earliest 
possible time to avoid using excessive amounts of storage for this 
purpose . 
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Test Response to a Request for Temporary Storage Services (TYPE = CHECK) 



The format of the DFHTS macro instruction to test the CICS/VS response 
to a request for temporary storage services is as follows: 




TYPE=CHECK 

[ ,NOSPACE=symr>olic address] 
[ ,NORESP=symbolic address] 
[ ,IDERROR=symbolic address] 
[ ,IOERROR=symbolic address] 
[ / INVREQ=symbolic address] 
[ ,ENERROR=symbolic address] 
[ ,ERROR=symbolic address] 



I Temporary Storage Response Codes 



The Assembler— language or PL/I programmer can access temporary storage 
response codes at TC&TSTR; the COBOL programmer can access temporary 
storage response codes at TCATSRC. In addition, the COBOL programmer 
can refer to the response codes by means of condition names (TSNORESP, 
TSIDERROR, and so on). (See the examples at the end of this 
discussion*) The possible response codes and the conditions to which 
they correspond are identified in the right— hand columns of Figure 5.7— 
1. DFHTS macro instructions for which the conditions are applicable are 
shown at the left. 
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1 - 
I Temporary 
| Storage 
| Request by 
| DFHTS Macro 
I Instruction 




Condition 


■ 
Response Code | 


Assembler 


COBOL | PL/I | 


| ALL 




NORESP 
(Normal response) 


X»00» 


LOW-VALUES | 000000001 
(TSHORESP) | | 


| GET,GETQ, 

| RELEASE, PURGE, 

| CHECK 




IDERROR 
(Identification 
error) 


X»02" 


12-2-9 | 00000010| 
(TSIDERROR) | | 


| PUT,PUTQ,GET, 
| GETQ, CHECK 




lOERROR 
(Input/Output 
error) 


X»04» 


12-4-9 | 000001001 
(TSIOERROR) | | 


| All 




IHVREQ 
(Invalid request) 


X»20» 


11_0_1-8-9 | 00100000| 
(TSINVREQ) | | 


| PUTQ,GETQ, 
| CHECK 




ENERROR 
(En-cry error) 


XM0» 


12-1-9 | 00010000| 
(TSENERROR)I | 


| PUT,PUTQ 




NOSPACE 
(No space on 
auxiliary storage) 


X»08« 


12-8-9 | 00001000| 
(TSNOSPACE ) | | 


| All 




ERROR 
(Any of above but 
unspecified) 


| (Note 2) 


(Note 2) | (Note 2)| 


| Notes: 










1 1. The names enclosed in parentheses in the COBOL column indicate | 
| the condition names generated by CICS/VS. These names nay be usedj 
I in testing for the conditions in a COBOL program* | 


| 2. The test for 
| condition; th 
| for Assembler 


the ERROR response is satisfied by a not equal I 
at is, not X'OO', not LOW-VALUES, or not 00000000 | 
, COBOL, and PL/I, respectively. | 



Figure 5*7—1. Temporary Storage Control Response Codes 

If the application programmer does not check for a particular 
response to a service request, and the exception condition corresponding 
to that response occurs, program flow proceeds to the next sequential 
instruction in the application program. 

The following examples show how to examine the response code provided 
by CICS/7S and transfer control to the appropriate user— written 
exception— handling routine* 



For Assembler language : 



DFHTS TYPE=GET, 

DATAID=UNIQNHE, 
TSDADDR=TES 
CLI TCATSTR^OO' 
BE GOOD 

DFHPC TYPE=ABEND 
GOOD DS OH 



NORMAL RESPONSE 
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For COBOL; 



DFHTS TYPE=GET, * 

DATAID=UNIQNME r * 

TSDADDR=YES 

IF TCATSRC = • • THEN GO TO GOOD. NOTE 12-0-1-8-9 NORESP. 

DFHPC TYPE=ABEND 



GOOD. 



Alternatively, the COBOL programmer may test responses by using the 
CICS/VS generated condition names. 

IF TSNORESP THEN GO TO GOOD. 



Fo r PL/I : 

DFHTS TYPE=GET, * 

DATAID=UNIQNME / * 

TSDADDR=YES 

IF TCATSTR=«0 , B THEN GO TO GOOD; /* NORMAL RESPONSE */ 

DFHPC TYPE=ABEND 
GOOD: 
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Operands of DFHTS Macro 

COND=YES 

indicates that control is to be returned to the application 
program when the request cannot be satisfied immediately 
because sufficient space is not available on the temporary 
storage data set. If this operand is omitted, the requesting 
task is suspended when no space is available and is resumed 
when the space becomes available* Space becomes available as 
it is released by other tasks in the system. 

DATAID=name 

specifies the unique alphameric name, up to eight characters in 
length, to be assigned to the temporary data to be stored. If 
this operand is omitted, the name is assumed to be in TCATSDI. 

Note : The application program should not construct a DATAID 
beginning with any of the hexadecimal characters PA through FF. 
Use of these characters for this purpose is reserved for 
cics/vs. 

ENERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the entry number specified or 
implied is invalid (that is, not within the limits of the 
message set) . 



ENTRY= 



specifies the number, relative to one, of the logical record to 
be retrieved from the message set. 

n 

is a decimal numeral to be taken as the relative number of 
the logical record to be retrieved. This number may be the 
number of any entry that has been written to the temporary 
storage message set. 



YES 



indicates that the number (in binary) of the logical record 
to be retrieved is in TCATSRN, a two— byte field. 



If this operand is omitted, CICS/VS retrieves (1) the first 
logical record from the message set, for the first retrieval 
request, or (2) the next sequential logical record following 
the last— retrieved record, for other than the first request. 
In the latter case, the relative record number is returned in 
TCATSRN. 

ERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an error occurs and the 
corresponding specific error routine operand (for example, 
IDERROR) has not been specified. 
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IDERROR=syrabolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the symbolic destination 
identification referred to by a GET, GETQ, RELEASE, or PURGE 
request cannot be found in either main storage or auxiliary 
storage . 

INVREQ=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if (1) a PUT or PUTQ request refers to 
data whose length is equal to zero or greater than the control 
interval size of the auxiliary data set minus 84 bytes for 
control information, or (2) the request is otherwise determined 
to be invalid. 

IOERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an unrecoverable input/output error 
occurs* 

NORESP=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if no errors occur during temporary 
storage processing* NORESP signifies "normal response." 

NOSPACE=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed when insufficient space is available on 
the temporary storage data set to contain the data in a PUT or 
PUTQ request. The user— written NOSPACE routine is passed 
control only if COND=YES is also specified in the PUT or PUTQ 
request. 



RELEASE= 



STORCLS= 



specifies the disposition of the temporary data following the 
move operation. 

YES 

the data and storage area used for the data are to be 
released after this operation. 

NO 

the data is to be retained, available for subsequent 
similar reference . 



specifies the class of storage to be obtained for the temporary 
data. This operand is ignored if TSADDR is specified. 



TERMINAL (TERM) 

specifies that the data is to be placed in a TERMINAL class 
storage area. 
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TEMPSTRG(TS) 

specifies that the data is to be placed in a temporary storage 
area. 

If this operand is omitted, TEMPSTRG is assumed. 

STORFAC= 

specifies the type of storage to be used for the temporary 
data. 

AUXILIARY 

indicates that the data is to be placed in auxiliary 
storage on a direct access storage device. 

MAIN 

indicates that the data is to be placed in main storage. 

If this operand is omitted, AUXILIARY is assumed. 

TSDADDR= 

specifies the symbolic address of the data portion 
(including the LL)f)S field) of the area in which the temporary 
data is stored. 

symbolic address 

is the symbolic address of the data portion of the storage 
area that contains the temporary data. 

YES 

indicates that the symbolic address of the data portion of 
the storage area has been placed in TCATSDA by the 
application programmer* 

If this operand is omitted, the appropriate symbolic address is 
assumed to be in TCATSDA. 

TYPOPER=REPLACE 

indicates that the specified record within the data set or 
message set is to be released and replaced with the record or 
data provided. If the message set does not exist (DATAID 
cannot be found), an invalid entry number error occurs, and the 
data provided is placed in temporary storage as in a normal 
PUTQ without TYPOPER=REPLACE specified. 

For TYPE=PUTQ, whenever REPLACE is specified the ENTRY operand 
must also be coded. 
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Part 6. CICS/VS Built-in Functions 
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Chapter 6.1. Introduction to CICS/VS Built-in Functions 



Several commonly used functions are available to the application 
programmer through CICS/VS macro instructions. These are functions 
which would otherwise have to be coded as separate subroutines by the 
programmer. These functions, referred to as built— in functions, provide 
the following services: 

Table search 

Phonetic conversion 

Verification of a data field 

Editing of a data field 

Bit manipulation 

Input formatting 

Weighted retrieval 

Requests for these services are communicated to the CICS/VS built— in 
functions program (DFHBFP) through the DFHBIF macro instruction. DFHBFP 
is then executed, at the priority of the requesting task, under control 
of the common control communication area (TCACCCA) of the TCA of the 
requesting task. Normally, control is returned to the next sequential 
instruction following the macro expansion in the requesting program; 
however, conditional branch options can be specified in the macro 
request if desired. 

Since DFHBFP uses TCACCCA, the application program must issue the 
DFHBFTCA macro instruction to copy the symbolic storage definition for 
this area and store any required information therein before issuing the 
DFHBIF macro instruction. Chapter 6.2 explains how to do this. 

The formats and operands of the DFHBIF macro instruction are 
described in Chapter 6.3. 
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Chapter 6.2. Storage Definition for Built-in Functions 

(DFHBFTCA Macro) 



When CICS/VS built— in functions (BIFs) are used in an application 
program, the symbolic storage definition for the TCACCCA used by these 
built— in functions must be copied into the application program. This 
copying is achieved by means of a DFHBFTCA macro instruction, which must 
immediately follow the statement that copias the TCA and the user's 
definition of a TWA, if any. 

The format of the DFHBFTCA macro instruction is as follows: 



where: 



OPTION= 

indicates which built— in functions are to be used. 

BASIC 

is required if any of the following functions are used 
table search, phonetic conversion, field verification, 
field editing, bit manipulation, or input formatting. 

WTRET 

is required if weighted retrieval is used. 

If the OPTION operand is omitted, both BASIC and WTRET are 
assumed . 

The following examples show the statements needed to copy the 
symbolic storage definitions referred to by the built— in functions, 
positioned as required. 

For Assembler language : 





COPY 


DFHTCADS 




NAME 


DS 


CL20 


TWA 


STREET 


DS 


CL20 


TWA 


CITY 


DS 


CLIO 


TWA 


STATE 


DS 


CL3 


TWA 




DFHBFTCA 




For COBOL: 









01 DFHTCADS COPY DFHTCADS. 

02 NAME PICT X (20) . NOTE TWA 

02 STREET PIC X (20) . NOTE TWA 

02 CITY PIC X(10) . NOTE TWA 

02 STATE PIC X (3) . NOTE TWA 
DFHBFTCA 
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F or PL/I : 



95INCLUDE (DFHTCADS) ; 

2 NAME CHAR (20), /*TWA*/ 

2 STREET CHAR (2 0), /*TWA*/ 

2 CITY CHAR (10), /*TWA*/ 

2 STATE CHAR (3); /*TWA*/ 
DFHBFTCA 
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Table Search Built-in Function (TYPE =TSE ARCH) 



The format of the DFHBIF macro instruction to request the search of a 
table is as follows: 



TYPE=TSEARCH 

[ ,ARG=symbolic address] 

[ ,TARGET=symbolic address] 

[ ,ATABLE=([sa1 ][ ,sa2|YES) ][ ,n1][, {n2|YES} ][ ,n3]) ] 

[,FTABLE=([ {sal | YES) ][ , {sa2|YES} ][ , {n1|YES} ] 

[,{n2|YES}]) ] 
[ ,ORDER={ASCENDING| DESCENDING) ] 
[ ,SUBST= {symbolic address| •literal value 1 } ] 
[ ,NOMATCH=symbolic address] 
[ ,INDEX=symbolic address] 
[ ,RANGE=YES] 
[ / ERROR=symbolic address] 




This macro specifies that a table is to be searched for a given 
entry, causing a corresponding value within that table or a second 
table, the address of the corresponding value, and the index of the 
selected entry (relative to one) to be returned. The search argument is 
compared on a byte— for-byte basis with a specified field of entries in 
the table being searched. Optionally, a default value can be returned 
in lieu of a corresponding value if the searched— for entry is not found. 
If an index is requested, but the entry is not found, an index value of 
zero is returned. 

N ote : In the syntax display, symbolic address and numeric value have, 
in some cases, been shortened to "xa" and "n" respectively. 



Returned Va lues 



An entry in the argument table that matches the search argument 
satisfies the table search built— in function. If such an entry is 
found, the address of the corresponding entry in the function table is 
returned in TCATSA5, a fullword field. 

If the TARGET operand is specified, the function value is returned in 
the location identified by that operand. If the function table contains 
more than one matching entry, the address (and the function value, if 
requested) of the first matching entry encountered during the search is 
returned. 

If the ORDER operand is specified, a binary search is performed, and 
the address returned is that of the first matching entry found. 
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If the ORDER operand is omitted, a sequential search is performed, 
starting at the last entry in the table, and the address returned is 
that of the last matching entry in the table* The index of the matching 
entry is returned in TCATSH4 and in the field identified by the INDEX 
operand if specified . 

If the RANGE=YES operand is specified, a matching entry satisfies the 
search as described above. If no matching entry is found, the search is 
satisfied in an alternative manner: 

• If ORDER=ASCENDING is specified, the argument table entry having 
the largest argument value less than the search argument satisfies 
the search. 

• If ORDER=DESCENDING is specified, the argument table entry having 
the smallest argument value greater than the search argument 
satisfies the search. 

Figure 6.3—1 defines the conditions that may occur during a table 
search and defines the possible return codes. 



I | Response Code | 


| Condition | Assembler | COBOL | PL/I | 


IMatch Found | X •00» | LOW-VALUES| '00000000 »B | 
I | | (TCATSMH) | | 

1 1 1 1 1 

IATABLE Field Address < Entry Address | X '04 1 | 12-4-9 | «00000100»B | 
| (symbolic address2 < symbolic | | (TCATSER2) | | 
| address 1) III I 
I I I I I 
IFTABLE Field Address < Entry Address | X •08» | 12-8-9 | '00001000 »B | 
| (symbolic address2 < symbolic | | (TCATSER1) | | 
| address 1) III I 

I I I I I 

| No Match Found | X 'F0' | '0» | »0» | 


1 Note: The names enclosed in parentheses in the COBOL column I 
| indicate the condition names generated by CICS/VS. These names may | 
| be used in testing for the respective conditions in a COBOL program. | 



Figure 6.3—1* Table Search Response Codes 



E xample — Separate Tables 



The following example shows how the DFHBIF TYPE=TSEARCH macro 
instruction can be used in an Assembler— language program. A four- 
character argument is matched against fields in a seven— entry argument 
table. If the search is satisfied, the address of a two— character 
corresponding field in the function table is placed in TCATSA5 and the 
index value of the matching entry is placed in TCATSH4. If no matching 
entry is found, a branch to BR1 occurs. 
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DFHBIF T£PE=TSEARCH, 
ARG=ARG1, 

ATABLE=(ATBL,AFLD,9,4,7) , 
FTABLE= (FTBL,FFLD,5,2 ) , 
ERR0R=ERR0R1, 
N0MATCH=BR1 



ERROR 1 



BR1 



ATBL 


DS 


0XL9 




DS 


XL5 


AFLD 


DS 


XL4 




DS 


6XL9 


FTBL 


DS 


0XL5 




DS 


XL3 


FFLD 


DS 


XL2 




DS 


6XL5 


ARG1 


DS 


XL 4 



FIRST ENTRY OF ARG TABLE 

FIRST ARGUMENT FIELD 

SPACE FOR SIX MORE ENTRIES 

FIRST ENTRY OF FUN TABLE 

FIRST FUNCTION FIELD 

SPACE FOR SIX MORE ENTRIES 
SEARCH ARGUMENT 



E xample — Complex Table 



The following example shows how the TYPE=TSEARCH macro is used for a 
complex table, that is, a table which contains both argument and 
function values. The search is similar to that above, except that only 
one table is described. 



DFHBIF TYPE=TSEARCH, 
ARG=ARG1, 

ATABLE=(TBL1,FLDA,5,2,3) , 
FTABLE= (TBL1,FLDF,5,3), 
ERROR=ERROR1, 
N0MATCH=BR1 



ERROR 1 



BR1 



TBL1 


DS 


0CL5 


FLDA 


DS 


CL2 


FLDF 


DS 


CL3 




DS 


2CL5 


ARG1 


DS 


CL2 



FIRST ENTRY OF ARG/FUN TABLE 

FIRST ARGUMENT FIELD 

FIRST FUNCTION FIELD 

SPACE FOR TWO MORE ENTRIES 

SEARCH ARGUMENT 
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Phonetic Conversion Built-in Function (TYPE=PHONETIC) 

The format of the DFHBIF macro instructions to request that a 16-byte 
field of data be encoded phonetically is as follows: 



DFHBIF| TYPE=PHONETIC 

| [ ,FIELD=symbolic address] 
| [ ,ERROR=symbolic address] 



This macro converts a name into a key, which can be used to access 
data in a data base data set. The key that is generated is based upon 
the sound of the name; names that sound alike, even though spelled 
differently, produce identical keys. For example, the names SMITH, 
SMYTH, and SMYTHE produce a phonetic key of S530. 

In addition to the phonetic conversion built— in function, a CICS/VS 
subroutine that performs similar conversion of keys is available for use 
by offline user— written programs. Together, these facilities allow the 
CICS/VS user to organize his file according to name (or any similar 
alphabetic key) and access the file using search arguments that may be 
misspelled or misunderstood to retrieve the reguired data. 



Returned Value 



The returned value is placed at TCAPHON. This value is the four— byte 
phonetic equivalent of the data passed to the built— in function. It 
consists of the first character of the data and three EBCDIC numbers 
representing the characters in the remainder of the data. 

If an error is detected during execution of the phonetic conversion 
macro, an error code is placed in TCAPHNR. Figure 6.3—2 shows the 
conditions that cause an error, and the codes that are returned. 



Response Code 



Condition 



Assembler | COBOL 



I PL/I 



1st character not alphabetic | 



X«50» | »&• | •&• 
| (TCAPINN) | 



Note ; 

The names enclosed in parentheses in the COBOL column are the 

condition— names generated by CICS/VS. 



| Figure 6.3—2. Phonetic Conversion Response Codes 
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P honetic Coding Me thod 

The application programmer need not be familiar with the CICS/VS method 
of phonetic coding to use the phonetic conversion function. Remember 
that the first character of the field to be coded is not changed; it 
becomes the first character of the returned value. Three digits are 
selected to represent the remaining characters in accordance with the 
following rules: 

Original Ch ar acte r Code Value 

B, P, F, V 1 

C, G, 3 r Kf Q, S, X, Z 2 

D, T 3 
L 4 
M, N 5 
R 6 

A, E, H, I, 0, Y, W, U, Bypassed, no 

blanks, and nonalphabetic code value 
characters 

• Lowercase letters are translated to uppercase. 

• Double letters are coded as a single letter. 

o Two or more adjacent letters with the same value are coded as a 
single letter. 

• If more than three EBCDIC numbers can be computed from the data, 
only the first three are used. 

o If fewer than three numbers can be computed from the name, the 

result is padded on the right with EBCDIC zeros to form a four— byte 
result . 



E xamples 

DFHBIF TYPE=PHONETIC, 
FIELD=NAME 

where NAME is a 16-byte field, yields results as follows: 



LEHWICKE yields L520 
WONG yields W520 
S00 yields S0O0 



Phoneti c Conv e rsio n Subrou tin e 

A CICS/VS subroutine that performs phonetic conversion of 16— character 
names in the same manner as the phonetic conversion built— in function is 
available for use by offline user— written programs. The subroutine can 
be called by a program running under any of the operating systems under 
which CICS/VS can be run. A 16-character name to be converted is 
provided as input to the subroutine; the four— byte phonetic equivalent 
of that name is returned as a result. The rules given above under 
"Phonetic Coding Method" are applied in the conversion process. 
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The general form of the macro instruction to invoke the subroutine is 
as follows: 

Fo r Assembler language : 

CALL DFHPHN, (lang, name, phon) 

For COBOL : 

CALL •DFHPHN 1 USING lang name phon. 

For PL/I : 

CALL DFHPHN (lang , name, phon) ; 

where: 



lang 



name 



phon 



is the symbolic address of a one— byte code indicating the 
programming language being used: X^FO 1 indicates COBOL or 
Assembler language; X^l* indicates PL/I. If an error occurs 
during processing of this request, X'SO* is returned in this 
location. If no error occurs, X^OO 1 is returned, and the 
location must be reset to indicate the programming language 
before the location can be reused. 



is the symbolic address of the field that contains the 16— 
character name to be converted. 



is the symbolic address of the field in which the four— byte 
phonetic equivalent of the name passed to the subroutine is 
returned to the calling program. 
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Field Verify Built-in Function (TYPE =F VERIFY) 



The format of the DFHBIF macro instruction to verify the contents of a 
data field is as follows: 




TYPE=FVERIFY 

[ / FIELD=symbolic address] 

[ ,LENGTH= {symbolic address|numeric value}] 

[ , ALPHA=symbolic address] 

[ ,NUMERIC=symbolic address] 

[ ,PACKED=symbolic address] 



This macro verifies that the contents of a data field are: 

o Entirely alphabetic: blanks or A-Z 

o Entirely EBCDIC numbers, with or without trailing sign: 0—9 (X^FO 1 
through X«F9») 

o Entirely packed decimal (COMPUTATIONAL— 3 in American National 
Standard (ANS) COBOL or FIXED DECIMAL in PL/I) 

A branch is made to an appropriate user— written routine accordingly. 

The ALPHA, NUMERIC, and PACKED operands may be specified in any 
combination or order, but at least one of them must be specified. The 
conditions specified are tested upon request in the order ALPHA, 
NUMERIC, PACKED, irrespective of the order of the operands. If none of 
the test conditions is met, control goes to the instruction following 
the DFHBIF TYPE=FVERIFY macro instruction in the application program. 



Returned Values 



The purpose of the field verify built— in function is to determine what 
kind of data must be processed and cause control to be transferred to an 
appropriate routine in the application program accordingly. The results 
of the verify built— in function can be tested by examining the response 
code at TCACHKR* Figure 6.3—3 indicates the conditions and response 
codes . 
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Response Code 




Condition 


| Assembler 


COBOL | 


PL/I | 


Packed field 






| X^O' 


11-4-9 
(TCACKPK) 


00100000 | 


Numeric field 






| X'^O^ 


No punches 
(TCACKNM) 


01000000 | 


Alphabetic field 






| X»80« 


12-0-1-8 

(TCACKAL) 


10000000 | 


Mixed field 






| X'EO* 


0-2-8 

(TCACKMX) 


11100000 | 


Note: 

The names in pare 
condition names g 
in testing for th 


ntheses in the COBOL column indicate the | 
enerated by CICS/VS. These names may be used | 
e respective conditions in a COBOL program. | 



I Figure 6.3—3. Field Verify Response Codes 



Ex ample 



DFHBIF TYPE=FVERIFY, 
FIELD=CONT, 
LENGTH=16 / 
ALPHA=MYROUT 



Execution of the DFHBIF macro instruction above causes the contents 
of CONT, a 16-byte field, to be checked to determine whether it contains 
only alphabetic characters and/or blanks. If it does, control is 
transferred to MYROUT. Otherwise, control returns to the instruction 
following this DFHBIF instruction in the application program. 
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Field Edit Built-in Function (TYPE=DEEDIT) 



The format of the DFHBIF macro instruction to edit a data field is as 
follows: 



i 1 

I 
DFHBIF | TYPE=DEEDIT 

| [ ,FIELD=symbolic address] 

| [ ,LENGTH= {symbolic address|numeric value}] 



This macro specifies that alphabetic and/or special characters, are 
to be removed from an EBCDIC data field. The remaining, numeric 
characters, are right— justified with zero padding at the left as 
necessary. If the field ends with a minus sign or 'CR 1 , a negative zone 
is placed over the low-order byte. 



Returned Values 

All bytes (except the rightmost byte) containing other than EBCDIC 
numeric characters are deleted from the data field. The remaining 
characters are right— justified in the field with zero padding at the 
left as necessary. If the field ends with a minus sign or a ■CR 1 , a 
negative zone (X'D 1 ) is placed over the rightmost (low— order) byte. The 
zone portion of the rightmost byte may contain any hexadecimal character 
from X^' through X^F 1 . The digit portion of this byte may contain one 
of the hexadecimal digits from X'O" through X 1 *) 1 . Where this is the 
case, the rightmost byte is returned unaltered (see the example below) . 
This permits the application program to operate on a zoned numeric 
field. In any case, the returned value is in the field that initially 
contained the unedited data. 



Example 

DFHBIF TYPE=DEEDIT, * 

FIELD=CONTG, * 

LENGTH=9 

Execution of this macro instruction removes all characters other than 
EBCDIC numbers from CONTG, a nine— byte field, and returns the edited 
result in that field to the application program. Say, for example, the 
field contains 14— 67 04/B before the DFHBIF TYPE=DEEDIT macro instruction 
is issued. After editing, it contains 00 146704B. 
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Bit Manipulation Built-in Functions 



The bit manipulation built— in functions are designed to change or test 
the state of specified bits in a given area of main storage. They are 
particularly useful for COBOL application programs, which are otherwise 
unable to manipulate bits* 

The built— in functions are invoked by different versions of the 
DFHBIF macro instruction, as follows: 

TYPE=BITSETON ensures that all bits selected by a specified bit 
pattern are on after execution of the macro. 

TYPE=BITSETOFF ensures that all bits selected by a specified bit 
pattern are off after execution of the macro. 

TYPE=BITFLIP causes the state of each bit selected by a specified 
bit pattern to be changed. 

TYPE=BITEST causes the state of each bit, selected by a specified 
bit pattern, to be tested, and an indicator to be set. 



TYPE=BITSETON 



The format of the DFHBIF macro instruction to set bits in a byte to an 
on— condition is as follows: 




I 

DFHBIF | 



TYPE=BITSETON 

[ , FIELD=symbolic address] 

[ ,BIT= {symbolic address | value) ] 

[ ,BITON=symbolic address] 

[ ,BlTOFF=symbolic address] 



This macro specifies 
pattern are on after exe 
specifies the eight— bit 
byte containing bits to 
single EBCDIC character 
or •»•. Alternatively, 
containing the mask can 
transferred to a specifi 
the byte) are on after c 



that all bits selected by a specified bit 
cution of the macro. The application programmer 
mask (£>it pattern) to be applied against the 
be operated on. The mask can be described by a 
within single quotation marks: for example, » 5* 
the symbolic address of a one— byte field 
be specified. If desired, control can be 
ed location if all affected bits (or all bits in 
ompletion of the bit manipulation. 



The returned value is the contents of the byte specified in the FIELD 
operand, with selected bits modified as specified. 
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E xample 

The macro instruction 



DFHBIF TYPE=BITSETON, * 

FIELD=DATAF, * 

BIT=PATERN, * 
BITON=BLABEL 



PATER N DC X'FF* 

ensures that all bits of the one— byte field DATAF are set on and causes 
a branch to 3LABEL. 



TYPE=BITSET0FF 



The format of the DFHBIF macro instruction to set bits in a byte to an 
of f— condition is as follows: 



DFHBIF | TYPE=BITSETOFF 

| [ ,FIELD=symbolic address] 

| [ ,BIT= {symbolic address | value} ] 

| [ / BITON=symbolic address] 

| [ ,BITOFF=symbolic address] 



This macro specifies that all bits selected by a specified bit 
pattern are off after execution of this macro. The application 
programmer specifies the eight-bit mask (bit pattern) to be applied 
against the byte containing bits to be operated on. The mask can be 
described by a single EBCDIC character within single quotation marks: 
for example, '5 1 or »M'. Alternatively, the symbolic address of a one- 
byte field containing the mask can be specified. If desired, control 
can be transferred to a specified location if all affected bits (or all 
bits in the byte) are off, after completion of the bit manipulation. 

The returned value is the contents of the byte specified in the FIELD 
operand, with selected bits modified as specified. 



TYPE=BITFLIP 

The format of the DFHBIF macro instruction to change the state of bits 
in a byte is as follows: 
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TYPE=BITFLIP 

[ ,FIELD=symbolic address] 
[ ,BIT= {symbolic address lvalue} ] 
[ ,BITON=sym&olic address] 
| [ ,BITOFF=symbolic address] 



This macro specifies that the state of each bit selected by a 
specified bit pattern is changed. The application programmer specifies 
the eight— bit mask (bit pattern) to be applied against the byte 
containing bits to be operated on. The mask can be described by a 
single EBCDIC character within single guotation marks: for example, *5* 
or •M». Alternatively, the symbolic address of a one— byte field 
containing the mask can be specified. If desired, control can be 
transferred to a specified location if all affected bits (or all bits in 
the byte) are on, or if all affected bits (or all bits in the byte) are 
off, after completion of the bit manipulation. 

The returned value is the contents of the byte specified in the FIELD 
operand, with selected bits modified as specified. 



TYPE=BITEST 



The format of the DFHBIF macro instruction to test the state of specific 
bits in main storage is as follows: 




DFHBIF| TYPE=BITEST 

I [ ,FIELD=symbolic address] 

j [ ,BIT= {symbolic address| value} ] 

I [ ,BITON=symbolic address] 

| [ ,BITOFF=symbolic address] 



This macro specifies that the state of 
pattern is to be tested and an indicator 
BIT operand specifies the eight— £>it mask 
applied against the byte containing bits 
can be described by a single EBCDIC chara 
marks: for example, »5* or , M I . Alternat 
a one— byte field containing the mask can 
control can be transferred to a specified 
(or all bits in the byte) are on, or if a 
in the byte) are off, after completion of 
built— in function is particularly useful 
otherwise unable to carry out bit manipul 



each bit in 
is to be set 
(bit pattern 
to be operat 
cter within 
ively, the s 
be specified 

location if 
11 affected 

the bit man 
for COBOL pr 
ation. 



a specified bit 
accordingly. The 
) that is to be 
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single quotation 
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Returned Values 



For BITEST, the result of the test is returned in TCABITR as shown in 
Figure 6.3-4. If BITON, BITOFF, or both BITON and BITOFF are specified, 
and if certain conditions are met as described in the explanations of 
these operands, control is transferred. 



Condition 



Tested Bits Are Off 
Tested Bits Are On 



Response Code in TCABITR 



Assembler 



X»00» 
X»F0« 



COBOL 



LOW-VALUES 
(TCABIFOF) 

•0« 
(TCABIFON) 



PL/I 



»00000000»B 
■0« 



Note: 

The names enclosed in parentheses in the COBOL column indicate 
the condition names generated by CICS/VS. These names may be 
used in testing for the conditions in a COBOL program. 



| Figure 6.3-4. Bit Test Response Codes 



The macro instruction 



DFH3IF TYPE=BITEST, 
BIT=»A», 
BITOFF=CLABEL 



causes a bit pattern of 11000001 to be applied to the one— byte field 
whose address is stored in TCABITF. If all tested bits are off, control 
is transferred to CLABEL. 
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Input Formatting Built-in Functions 

There are two versions of the DFHBIF built-in function to handle input 
formatting, as follows: 

TYPE=DEFLDNM defines keywords in free— format input 

TYPE=INFORMAT specifies formatting of terminal input 

Both these versions are described later in this chapter. 

The input formatting built— in function allows free— format terminal 
input to be converted into a predefined fixed format that can be 
processed by the application program.. The application program can 
accept any of three forms of input from the terminal. These forms are 
discussed in order of increased flexibility below. 



FIXED FORMAT 

This is the simplest case, but it requires a rigid adherence to form. 
The input transaction must be identical in format to the fixed internal 
format established by statements in the application program. For 
example, assume the fixed internal format for data consisting of a 
transaction identification; last name, first name, and middle initial; 
and identification number is as follows: 

C ols JM* 57 1921 31 33 M 36 42 

EOB 



TRANS W LAST 


W 


FIRST 


Wr m 


W 


ID 


ID NAME 




NAME 


i 




NO 



The input transaction must be formatted as shown by the following 
example: 

INQR HUGHES JOHN Q 096556 EOB 

Each input field must be entered by the terminal operator in the 
positions established for it in the fixed internal format. 



POSITIONAL FORMAT 

This option allows the terminal operator to enter a system— programmer 
selected field-separator character to indicate the end of a field or the 
absence of a field. The order of the fields on input must be the same 
as the order established for the fixed internal format; the field 
lengths need not be the same. If other fields follow, the end of a 
field or the absence of a field within the input must be indicated by a 
field— separator character. 

Assume that input consisting of a transaction identification; last 
name, first name, and middle initial; and identification number is to be 
entered from a terminal. Further assume that the input formatting 
built— in function is invoked by the application program to process this 
input, recognizing the slash (/) as a field— separator character. The 
following examples show permissible free— format positional input. Each 
input transaction is terminated by an end— of— block (EOB) character. 
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Complete input 
INQR/HUGHES/JOHN/Q/09 6556 E03 

Middle initial unknown 
INQR/HUGHES/JOHN//096556 EOB 

Middle initial and identification number unknown 
INQR/HUGHES/JOHN EOB 



KEYWORD FORMAT 

The keyword format provides an even greater degree of flexibility in 
that terminal input can be entered in any order. The terminal operator 
need only be familiar with the keyword identifiers that have been 
established for the input fields. Each keyword identifier consists of 
up to four characters selected by the application programmer. The 
keyword identifier must be preceded by a field— name start character and 
followed by a field— separator character, both of which must be specified 
at system initialization by the system programmer. If either of these 
characters is not specified, the default assumed is a blank; however, 
since the field— name start character must be different from the field- 
separator character, it is invalid to take both defaults. 

As an example, assume that keyword identifiers are established by use 
of the TYP£=DEFLDNtf macro (described later in this chapter) as follows: 

LN — last name field 

FN — first name field 

MI — middle initial field 

ID — identification number 

Further assume that the period has been specified as the field— name 
start character and the equal sign has been specified as the field- 
separator character. The following examples show permissible free- 
format keyword input. 

• Complete input 
INQR.FN=JOHN.MI=Q.ID=096556.LN=HUGHES EOB 

• First name unknown 
INQR.LN=HUGHES.MI=Q.ID=096556 EOB 

• First name and identification number unknown 
INQR.LN=HUGHES.MI=Q EOB 

The first entry in each of these examples is the transaction 
identification. Since CICS/VS expects this identification, it must be 
first and no keyword identifier is required for it. Succeeding data 
fields are entered in any order. The input is terminated by the end— of— 
block (EOB) character. 
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COMBINATION INPUT 

CICS/VS DFHBIF macro instructions can be included in an application 
program to permit a combination of fixed, positional, and Keyword input. 
For example, the following variations may be allowed. 

• Complete input 
INQR.LN=HUGHES.FN=JOHN/Q/096556 EOB 
INQR.FN=JOHN.LN=HUGHES.MI=Q/096556 BOB 
INQR/HUGHES/JOHN/Q 096556 EOB 

• First name unknown 

INQR. LN=HUGBES//Q/096 556 EOB 
INQR/HUGHES//Q.ID=096556 EOB 
INQR HUGHES//Q 096556 EOB 

• First name and identification number unknown 
INQR.LN=HUGHES//Q EOB 
INQR/HUGHES.MI=Q EOB 

INQR HUGHES. MI=Q EOB 

The application programmer can write a program to handle free— format 
input entered from a terminal. The free— format input may be either 
positional or keyword— oriented, or both, and may be entered in 
combination with fixed— format input. Examples are: 

INQR/HUGHES/JOHN/Q/096556 EOB positional 

INQR.FN=JOHN.MI=Q.ID=096556.LN=HUGHES EOB keyword-oriented 

A task that issues DFHBIF macro instructions to provide input 
formatting must be attached to a terminal. 



St orage Defin i tion 

As a first step in defining storage, the programmer must copy the 
CICS/VS control section of the terminal input/output area (TIOA) into 
his program. Definitions of the fields for which input data may be 
entered should follow the definition of the CICS/VS control section. 
For example, the Assembler— language programmer may write the following 
code: 

COPY DFHTIOA 



* 






BEGINNING OF TIOA 


TIOATI 


DS 


CLU 


TRANS ID 


TIOALN 


DS 


CL15 


LAST NAME 


TIOAFN 


DS 


CL9 


FIRST NAME 


TIOAMI 


DS 


CL1 


MIDDLE INITIAL 


TIOA ID 


DS 


CL6 


IDENTIFICATION 



TIOADBA is the CICS/VS— established name representing the first byte 
of the user's section of the TIOA for Assembler language only. 
Succeeding names are application— programmer— selected identifiers of the 
input fields. (The copying of symbolic storage definitions is described 
in Part 2 . ) 
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TYPE=DEFLDNM 



The format of the DFHBIF macro instruction that defines keywords in 
free— format input is as follows: 



DFHBIF| TYPE=DEFLDNM 

| ,NAMES= (keyword[ , keyword, ... ]) 
| , LABEL=syrabolic address 



If this macro instruction is used in a COBOL program , it must appear 
in the Working Storage section of the program. It must appear with 
other data definitions in an Assembler— language or PL/I program. This 
macro instruction is not needed if only free— format positional input is 
to be handled by a program. 

For example, a DFHBIF TYPE=DEFLDNM macro instruction defining 
keywords that the user can enter to refer to fields of the TIOA in the 
previous section, "Storage Definition," is: 

DFHBIF TYPE=DEPLDNM, * 

NAMES=(TI,LN,FN,MI,ID) , * 

LABEL=DEFI 

In this example, the keywords are formed by taking the last two 
characters of the TIOA field names. Use of similar names within the 
DFHBIF macro instruction and the TIOA definition is wise programming 
practice, but not a requirement. Thus, the following macro instruction 
is also acceptable. 

DFHBIF TYPE=DEFLDNM, * 

NAMES= (TRAN, LAST, FIR, MID, IDEN) , * 

LABEL=MYIN 

In both of these examples, the first keyword is a dummy name, because 
the first field will contain the transaction identification. The 
keyword for this field is provided to obtain the correlation between the 
TIOA definition and the macro instruction, but would not appear in the 
free— format input from the terminal. 



R equired Deli m iters 

When providing free— format keyword-oriented input capabilities to 
terminal users, the application programmer, working with system 
programmers, must define a field— name start character and a field- 
separator character for the system before initialization. (See the 
CICS/VS System Programmer's Reference Manua l for details.) 



Chapter 6.3. CICS/VS Built-in Functions (DFHBIF Macro) 473 



TYPE=INFORMAT 

The format of the DFHBIF macro instruction that specifies formatting of 
terminal input is as follows: 



DFHBIF | TYPE=INFORMAT 

| / FIELDS= (symbolic address [, symbolic address,...]) 

| [ ,NAMES= {symbolic address| YES} ] 

| [ ,LENGTH= {symbolic address | numeric value}] 

| [ ,ERROR=symbolic address] 



Data entered as free— format input (keyword-oriented or positional) is 
read into a TIOA in the same manner as other data entered from a 
terminal. CICS/VS places the address of the TIOA into TCTTEDA (as it 
must be for a formatting operation) . To provide for the formatting of 
this free-format input, a DFHBIF TYPE=INFORMAT instruction should be 
issued immediately following the terminal control (DFHTC) macro 
instruction that causes data to be moved into the TIOA to make sure that 
the address of the TIOA containing data to be formatted is in TCTTEDA. 

This built— in function reformats data from the input TIOA into a 
CICS/VS— acquired TIOA. Data is moved from the input TIOA into locations 
in the output TIOA named in the FIELDS operand. The length of the data 
moved is the difference between displacements of the field being 
processed and the next field named in the FIELDS operand. All data is 
treated as alphameric, is left justified in each output field, and is 
padded on the right with blanks, or is truncated, as necessary. 

If, however, the form of input is positional and an input data item 
is longer than the internal field defined for it, the data item is not 
truncated unless it is for the last field. Instead, a response code of 
4 is set, as described below, and the data is treated as fixed— format 
input. (The reason for this treatment is that mixed formats are 
allowed, so it is impossible for the built— in functions program to 
distinguish between an intentional fixed-format input for more than one 
field and a positional input of excessive length for a single field.) 

The input TIOA supplied by the user is released by the built— in 
function program (DFHBFP) . The address of the fixed— format TIOA is 
returned in TCTTEDA to the application program. The application 
programmer should establish addressability to this TIOA immediately, 
just as for any TIOA used in the program. (See the instructions for 
copying symbolic storage definitions in Part 2.) 

If the DFHBIF TYPE=INFORMAT macro instruction is issued immediately 
following the read instruction, the address of the TIOA containing the 
data to be formatted will be stored in TCTTEDA. If any intervening 
macro instructions are issued, the application programmer is responsible 
for saving and restoring the contents of TCTTEDA. For COBOL, TIOABAR 
must be loaded before a DFHBIF because the expansion will contain "CALL 
DFHCBLI USING fields." 
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Returned Values 



The address of the fixed— format TIOA containing the reformatted data is 
available in TCTTEDA. This address must be loaded into TIOABAR, the 
base register for the area. 

Certain error conditions may be detected during execution of the 
DFHBIF TYPE=INFORMAT macro instruction. In such cases, an error 
indication (response code) is returned to the application program in 
TCAINRC, a one— byte field. The error conditions that may occur and the 
response code for each are shown in Figure 6.3—5. For error conditions 
other than X»F4», no reformatted data is returned; that is, TCTTEDA does 
not contain the address of a fixed— format TIOA containing the 
reformatted data. 



Condition 



Response Code in TCAINRC 



Assembler | COBOL 



I PL/I 



No Error 

The input data does not contain 
field— name start or field— separator 
characters. (Such data may not be 
erroneous, if deliberately entered 
in this manner.) 

The input data contains two field- 
name start characters with no field- 
separator character between them. 

The input data contains an invalid 
name . 

A field name is specified in the 
input data, but no DFHBIF TYPE= 
DEFLDNM macro instruction is 
contained in the application 
program . 

The length of an input data field 
exceeds defined internal field size. 

The subparameters of the FIELDS 
operand are not specified in 
order of ascending displacement 
within the TIOA. 



X«00' 
X«20» 



X«F1» 



X • F2 



X»F3 



X«F4» 



X'FS 1 



LOW-VALUES 
(TCAINNOE) 

11-0-1-8-9 
(TCAINALS) 



■1» 

(TCAINER1) 

•2» 

(TCAINER2) 

■3» 

(TCAINER3) 



141 
(TCAINER4) 

»5» 

(TCAINER5) 



00000000 
00100000 



•2» 



•3» 



Note : 

The names enclosed in parentheses in the COBOL column indicate 
the condition names generated by CICS/VS. These names may be 
used in testing for the conditions in a COBOL program. 



| Figure 6.3—5. Input Formatting Response Codes 

Note : Application programmers and terminal operators should be aware 
that if fixed— format input is provided to an application program 
designed to accept free— format input, field overrun (X , F4 I ) errors are 
apt to occur. 
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Examples 

Assume the TIOA definition and the first DFHBIF TYPE=DEFLDNM macro 
instruction above. Further assume that the period has been established 
as the field—name start character and the equal sign and the slash as 
field— separator characters. 

The free— format positional input 

INQR/HUGHES/JOHN/Q/09 6556 EOB 

can be processed by issuing the following macro instruction: 

DFHBIF TYPE=INFORMAT, * 

FIELDS= (TI0AIN,TI0A1N,TI0AFN,TI0AMI,TI0AID) 

The free— format keyword input 

INQR.FN=JOHN.MI=Q.ID=096556.LN=HUGHES EOB 

can be processed by issuing the following macro instruction: 

DFHBIF TYPE=INFORMAT, * 

FIELDS= (TIOAIN,TIOALN,TIOAFN,TIOAMI,TIOAID) , * 

NAMES=DEFI 

A mixture of free— format positional and keyword input can be handled 
by this latter form of DFHBIF TYPE=INFORMAT macro instruction. For 
example, 

INQR.LN=HUGHES//Q/096556 EOB 
will be handled correctly. 
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Weighted Retrieval Built-in Functions 

The weighted retrieval built— in function allows the application 
programmer to search a group of records in a VSAM key sequenced data 
set, selecting only those records that satisfy or are closest to the 
selection criteria provided. 

In general, a series of DFHBIF macro instructions is involved. 

1. A DFHBIF TYPE=WTRETST macro instruction indicates the start of a 
weighted retrieval operation. 

2. One or more DFHBIF TYPE=WTRTPARM macro instructions provide the 
specifications to be used by CICS/VS in the weighted retrieval 
process. 

3. One or more DFHBIF TYPE=WTRETGET macro instructions retrieve one or 
more selected records. 

4. A DFHBIF TYPE=WTRETREL macro instruction releases the VSAM work 
area (VSWA) and other main storage used for the weighted retrieval 
process. 

5. A DFHBIF TYPE=WTRETCHK macro instruction performs a check on the 
success of a phase of the weighted retrieval process. 

Each of these macro instructions is discussed more fully below. 

Each record with a specified partial key (beginning with the first 
one, or with the one having a specified relative number) is examined to 
see whether entries in certain other fields of the record match the 
values specified for those fields as selection criteria. Matching may 
be on exact comparison or within a given range. 

Differentiating among individuals is one example of an area in which 
weighted retrieval processing is advantageous. In federal and state 
governments, the banking industry, and many other application areas 
dealing with large populations, name alone does not provide unique 
identification. A number of people may have the same name, so 
additional identifying characteristics are required. Such attributes as 
sex, race, birth date, address, relatives, and employment tend to permit 
unique identification. A basic example showing weighted retrieval on 
the basis of last name, first initial, and mother^ maiden name is given 
later in this chapter. 

Each comparison performed during weighted retrieval causes a match 
value to be added to a current total counter maintained automatically by 
CICS/VS. If the comparison yields a match, the match value is also 
added to a weighted counter. If the compared fields do not match, the 
no— match value is subtracted from the weighted counter. Fields in the 
search criteria or in a record being examined that contain a predefined 
null character may be ignored (not included in the search) if desired. 

When all fields to be considered in the selection process have been 
examined, a weighted qualification percentage (WQP) is calculated for 
the record. If this percentage is within the limits of acceptability 
established in the application program, the percentage and complete key 
of the record are saved in a key— save storage block. 

After all records with the specified partial key have been examined, 
the saved keys are sorted into descending percentage— value order. Under 
normal processing, the records whose keys have been saved are retrieved 
one at a time and made available to the application program in order of 
decreasing acceptability. A further judgment as to acceptability or 
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verification of identifiers is then made by the application program, 
which may involve the terminal operator in the final selection. 

If the number of saved keys exceeds a maximum established in the 
application program (say, n) , all keys having a weighted qualification 
percentage (WQP) equal to or lower than that of the "n+1"th key are 
dropped. If this dropping causes less than the application program- 
specified maximum number of keys to be saved but some keys are saved (as 
in Figure 6.3—6), no indication is given to the application program. 
However, if all percentages are the same so that all keys are dropped 
thereby, control is passed to an overflow routine (if one is specified 
in the application program) . If the amount of storage required for 
saved keys exceeds the amount of storage available for keys, an overflow 
also occurs, and the application program is notified. An alternative, 
lower maximum can be established by the application program. The 
maximum number of records that can be retrieved is restricted by the 
maximum size of a key-save block (64K) . This maximum is calculated as 
storage size divided by saved key length plus one. 



ir 



WQP of these records is 

greater than that 

of N+1 



WQP of these records 

(including N) is equal 

to that of N+1 



WQP of these records is 

less than that 

of N+1 



10 



V 



v 
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40 

yv 



60 



70 



80 
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90 

y 



Keys of 

records evaluated 

by Weighted Retrieval 



I Figure 6.3—6. Selection of Records by Weighted Retrieval 
No^es : 

1. Because of the potential effect of weighted retrieval operations on 
system performance, this function should not be used 
indiscriminately. The amount of file accessing and the use of main 
storage should be taken into account. 

2. The computations applied by CICS/VS in weighted retrieval 
processing can be expressed as follows: 
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Let MV = match value 

NMV = no— match value 

a. The weighted counter (WC) , which holds the sum of all match 
values that had a match minus the sum of all no— match values 
that had no match: 

WC = (MV + MV + ... + MV ) - (NMV + NMV + ... + NMV ) 

b. The sum of all match values specified in WTRTPARM macro 
instructions for the weighted retrieval operation; the 
potential count (PC) : 

PC = MV + MV + .. . MV 

c. The sum of all match values generated by the record comparisons 

(excludes those comparisons bypassed because the null character 
is present); the current total counter (CTC) : 

CTC = MV + MV + . . . + MV n<k 

d. The weighted potential (WP) : 

WP = PC + CTC 
2 

e. The weighted qualification percentage (WQP) : 

WQP = WC 

WP 

An overall effect of this method of computation is to provide a 
minimum weighting penalty for records having absent fields but yet 
prevent them from being chosen in preference to records that have all 
identifiers present. 



INITIATE WEIGHTED RETRIEVAL (TYPE=WTRETST) 

The format of the DFHBIF macro instruction to indicate the start of a 
weighted retrieval operation is as follows: 
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DFHBIFI TYPE=WTRETST 

[ ,DATASET=syrabolic name] 

[ ,RDIDADR=symbolic address] 

[ ,INPUTNO= {symbolic address | numeric value|YES}] 

[ ,INPUTST= {symbolic address| numeric value|YES}] 

[ , INPUTPC= ([ suboperandl ][ , suboperand2 ]) ] 

[ ,NRECDS= {symbolic address | numeric value|YES} ] 

[ ,NORESP=symbolic address] 

[ ,DSIDER=symbolic address] 

[ ,NOTOPEN=symbolic address] 

[ ,NOTFND=symbolic address] 

[ ,INVREQ=symbolic address] 

[ ,IOERROR=symbolic address] 

[ ,OFLOW=symbolic address] 

[ / ILLOGIC=symbolic address] 



Returned Values 



The address of a V5AM work area (VSWA) to be used by weighted retrieval 
throughout this series of weighted retrieval operations is returned in 
TCAWRAA, a four-byte field. Since any CICS/VS macro instruction issued 
within the application program may cause the contents of TCAWRAA to be 
changed, the application programmer should save this address. It must 
be restored in TCAWRAA prior to any subseguent DFHBIF macro instruction 
included in this series of weighted retrieval operations. A response 
code indicating how CICS/VS has responded to this request is returned in 
TCAWTRC, a one— byte field (see "Test Response to a Request for Weighted 
Retrieval," later in this chapter.) 



ESTABLISH SELECTION CRITERIA (TYPE=WTRTPARM) 



The format of the DFHBIF macro instruction to pass selection criteria to 
CICS/VS is as follows: 



TYPE=WTRTPARH 

[ ,FIELD1= ([symbolic address ][ , numeric value ][, char ]) ] 

[, FIELD 2= ([symbolic addressl ][ , symbolic address2]) ] 

[ ,NULL={symbolic address | character value|YES}] 

[ ,MATCH= {symbolic addressl numeric value}] 

[ ,NOMATCH= {symbolic addressl numeric value}] 

[ ,RANGE= (suboperandl ,suboperand2[ , suboperand3 ] ) ] 




One of these macro instructions must be coded for each field that is 
to be examined during the selection process* Match and no— match values 
are established separately for each field. Then, during weighted 
retrieval processing, the applicable match and no— match values for 
examined fields of a record are used to determine a weighted 
qualification percentage for the record. 
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RETRIEVE SELECTED RECORDS (TYPE=WTRETGET) 



The format of the DFHBIF macro instruction to retrieve a record that has 
been saved by the weighted retrieval built— in function is as follows: 




TYPE=WTRETGET 

[ ,NORESP=symbolic address] ■ 
[ ,ENDFILE=symoolic address] 
[ , NOTOPEN=symbolic address] 
[ ,NOTFND=symbolic address] 
[ ,INVREQ=symbolic address] 
[ ,IOERROR=symbolic address] 
[ ,OFLOW=symbol ic address] 
[ , ILLOGIC=symbolic address] 



This macro specifies that next record saved by weighted retrieval (as 
ordered according to decreasing weighted gualif ication percentage) is to 
be retrieved. 

Before this macro instruction is executed, TCAWRAA must contain the 
address of the VSAM worlc area (VSWA) used in this series of weighted 
retrieval operations. 



Returned Values 



A record saved as the result of weighted retrieval is returned to the 
application program. The address of this record is contained in VSWAREA 
within the VSWA provided by the WTRETST macro instruction. The length 
of the record is returned in VSWALEN. 

In addition, the contents of several half word fields are significant. 
TCAWGH1 contains the highest percentage of acceptability for this 
weighted retrieval operation, TCAWGH2 contains the lowest percentage of 
acceptability for this weighted retrieval operation, TCAWGH3 contains 
the percentage of acceptability of this record, and TCAWGH4 contains the 
number of records left to be presented to the user. After the first 
DFHBIF TYPE=WTRETGET macro instruction, TCAWGH5 contains a count of any 
records dropped to remain within the maximum specified in the NRECDS 
operand of the WTRETST macro instruction. On succeeding WTRETGETs, 
TCAWGH5 contains zero. The full key of the returned record is returned 
at the location specified in the RDIDADR operand of the DFHBIF 
TYPE=WTRETST macro instruction initiating this weighted retrieval 
operation. 

TCABFTR, a one— byte field, contains the response code that describes 
the CICS/VS response to this DFHBIF TYPE=WTRETGET macro instruction. 
This response code can be interrogated as described under "Test Response 
to a Request for Weighted Retrieval," later in this chapter. 
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RELEASE WEIGHTED RETRIEVAL STORAGE AREAS (TYPE=WTRETREL) 



The format of the DFH3IP macro instruction to specify that the VSWA 
established when the DFHBIF TYPE=WTRETST macro instruction is issued and 
the main storage used for saving the records is released is as follows: 




TYPE=WTRETREL 

[ ,NORESP=symbolic address] 
[ ,INVREQ=symbolic address] 
[ ,ILLOGIC=syrabolic address] 



TEST RESPONSE TO A REQUEST FOR WEIGHTED RETRIEVAL 
(TYPE=WTRETCHK) 



The general format of the DFHBIF TYPE=WTRETCHK macro instruction is as 
follows: 



DFHBIF | TYPE=WTRETCHK 




,NOTOPEN=symbolic aaaress 
, NOTFND=symbolic address] 
,INVREQ=symbolic address] 
,ENDFILE=symbolic address] 
,IOERROR=symbolic address] 
/ OFLOW=symbolic address] 
,ILLOGIC=symbolic address] 



| WEIGHTED RETRIEVAL RESPONSE CODES 



The response codes and the conditions to which they correspond are 
identified in the right— hand columns of Figure 6.3—7. DFHBIF macro 
instructions for which the conditions are applicable are shown at the 
left. 

If checking for a response to a weighted retrieval macro instruction 
is not provided, and if the exception condition corresponding to that 
response occurs, program flow proceeds to the instruction following the 
weighted retrieval macro instruction in the application program. 
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DFHBIF Macro 
Instruction 



Condition 



Response Codes in TCAWTRC 






Assembler! COBOL 



I PL/I 



WTRETST, 
WTRETGET, 
WTRETREL, 
WTRETCHK 

WTRETST, 
WTRETCHK 



WTRETST, 

WTRETGET, 

WTRETCHK 

WTRETST, 

WTRETGET, 

WTRETCHK 

WTRETGET, 
WTRETCHK 

WTRETST, 
WTRETGET, 
WTRETREL, 
WTRETCHK 

WTRETST, 

WTRETGET, 

WTRETCHK 

WTRETST , 

WTRETGET, 

WTRETCHK 

WTRETST, 
WTRETGET, 
WTRETREL, 
WTRETCHK 



NORESP 
(Normal response) 



DSIDER 
(Data set identi- 
fication error) 

NOTOPEN 
(Data set not 
open) 

NOTFND 
(Record not found ) 



ENDFILE 
(End of file) 

INVREQi 

(Invalid request) 



IOERROR 
(Input/Output 
error) 

0FL0W2 
(Overflow ) 



ILLOGIC3 
(VSAM error) 



X»00» 



X'C1' 



X»C2» 



X»C8» 



X»C4» 



x'ca 1 



X»C5» 



1*06' 



X'C? 1 



LOW-VALUES | 000000001 
! ! 

I I 



»B» 



H» 



| •B« 



i 

| * B » 

I 



Notes : 

1. If the data set is not a VSAM file, the field TCAWRAA is set to 
zero. CICS/VS file control handles other errors of thi .:> type, 
in which case, TCAWRAA contains the address of the FCT entry 
for the data set. 

2. For WTRETST, this response indicates that the system-defined 
maximum storage GETMAIN (64K) is insufficient to hold all 
retrieved record keys and these records have the same percentage 
of acceptability. In this case, the terminal operator must 
specify a relative record number (the relative position of the 
first record to be retrieved among the retrieval records) and a 
number of records (NRECDS) to be presented. For WTRETGET, this 
response means that no records were returned because all had 
identical percentages of match and not all could be returned 
because of the limit specified in NRECDS. 

3. This response indicates that a VSAM error tnat does not fall into 
one of the above categories has occurred. The VSWA contains the 
VSAM request parameter list that contains the VSAM logical error, 
error. 

| Figure 6.3—7. weighted Retrieval Response Codes 
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E xample 

Assume that, for purposes of state welfare applications, a VSAM file 
labeled SRCHFILE is maintained on magnetic disk. SRCHRECD is an area of 
storage that holds individual records retrieved from the file. The file 
is to be searched to retrieve up to 100 records that satisfy (or coma 
closest to satisfying) the criteria: last name = SMITH, first initial = 
J, and mother's name = MARY. 





COPY 


DFHTCADS 


LNAME 


DS 


CL18 


FINIT 


DS 


CL1 


MOM 


DS 


CL7 



DFHBFTCA 0PTI0N=WTRET 



SRCHRECD DSECT 

USING *,RCDBASE 
LAST DS CL18 
FIRST DS CL1 
MOTHER DS CL7 

DFHBIF TYPE=WTRETST, * 

DATASET=SRCHFILE, * 

RDIDADR=KEYFLD, * 

INPUTNO=100, * 

INPJTST=10, * 

INPUTPC=(100,80) , * 

NRECDS=50, * 
N0RESP=START0K 

(error processing) 

STARTOK DS OH 

L VSWABAR,TCAWRAA 

DFHBIF TYPE=WTRTPARM, * 

FIELD1= (LNAME, 18, C) , * 

FIELD2= (SRCHRECD, LAST) , * 

MATCH=50 
DFHBIF TYPE=WTRTPARM, * 

FIELD1= (FINIT, 1 ,C) , * 

FIELD2= (SRCHRECD, FIRST) , * 

MATCH=30 
DFHBIF TYPE=WTRTPARM, * 

FIELD1=(M0M,7,C) , * 

FIELD2= (SRCHRECD, MOTHER) , * 

MATCH=20 
WRGET DS OH 

ST VSWABAR,TCAWRAA 

DFHBIF TYPE=WTRETGET, * 

NORESP=GETOK, * 

ENDFILE=ENDPROC 

(error processing) 

GETOK DS OH 

L RCDBASE,VSWAREA GET ADDRESSABILITY TO RECORD 
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(on first WTRETGET, check to see whether too many 
records have been skipped, enough records returned, 
acceptable range of % returned, and the like) 



(process retrieved record) 
B WRGET 



ENDPROC DS OH 



ST VSWABAR,TCftWRft& 
DFHBIF TYPE=WRETREL 
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Operands of DFHBIF Macro 

ALPHA=symbolic address 

is the address to which control is to be passed if the field 
consists entirely of alphabetic characters (A through Z) and/or 
blanks. 

ARG=symbolic address 

is the symbolic address of the field that contains the search 
argument; if omitted, the address is assumed to be in TCATSA1 , 
a fullword field. 

ATABLE= 

is a description of the table to be searched (the argument 
table) . 

symbolic address! 

is the address of the first entry in the argument table; if 
omitted, the address is assumed to be in TCATSA2, a 
fullword field. 

symbolic address2 or YES 

is the address of the field in the first entry of the 
argument table to be compared with the search argument. If 
YES is specified, the field address is assumed to be in 
TCATSA4, a fullword field. If this operand entry is 
omitted, symbolic address2 is assumed to be the same as 
symbolic address! . If specified, the address represented 
by symDolic address2 must be equal to or greater than the 
address represented by symbolic addressl. If it is not, 
bit 4 of TCATSRC is set on and no search is made. 

numeric valuel 

is the length of each entry in the argument table 
(including any other fields in the entry or slack bytes 
required for boundary alignment) . A value in the range 
from 1 through 32767 may be specified. If this operand 
entry is omitted, the length is assumed to be in TCATSH2, a 
halfword field. 

numeric value2 or YES 

is the length of the field in the argument table to be 
compared with the search argument. If YES is specified, 
the length is assumed to be in TCATSAF, a one— byte field. 
If this operand entry is omitted, numeric value2 is assumed 
to be the same as numeric valuel. If specified, the value 
must be between 1 and 255 inclusive. If numeric valuel is 
not within this range, numeric value2 must be specified. 

numeric value3 

is the maximum number of entries to be searched. A value 
in the range from 1 through 32767 may be specified. if 
this operand entry is omitted, the numeric value is assumed 
to be in TCATSH1, a halfword field. 

If one or more of these operand entries are omitted, but other 
operand entries follow, the comma that ordinarily follows an 
omitted entry must be included in the operand. 
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BIT = 

specifies the bit pattern (mask) to be applied to the specified 
byte. 

symbolic address 

is the address of a byte that contains the bit pattern. 

value 

is a single EBCDIC character enclosed in single quotation 

marks. 

If this operand is omitted, the bit pattern is assumed to be in 
TCABITV, a one-byte field. 

BITOFF=symbolic address 

is the symbolic address to which control is transferred if — 

• For BITSETON, BITSETOFF, or BITFLIP: 

All bits in the specified byte are off after the operation 
is completed 

• For BITEST: 

All bits that are on in the bit pattern are off in the 
field that is tested 

BITON=symbolic address 

is the symbolic address to which control is transferred if — 

• For BITSETON, BITSETOFF, or BITFLIP: 

All bits in the specified byte are on after the operation 
is completed 

• For BITEST: 

All bits that are on in the bit pattern are on in the field 
that is tested 

DATASET=symbolic name 

is the one— to eight-character identification of the VSAM data 
set from which the retrieval is to be made; if omitted, the 
data set identifier is assumed to be in TCAWTDI, an eight— byte 
field. 

DSIDER=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the data set specified by the 
DATASET operand cannot be located. DSIDER signifies "data set 
identification error" . 

ENDFILE=symt>olic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an end-of— f ile condition is 
detected. 
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ERflOR=symbolic address 

is the address to which control is to be passed if an error 
occurs. This branch is taken, for example, if the address 
specified for the function field to be examined is lower than 
the address specified for the first function table entry. 

PIELD=symbolic address 

is the symbolic address of the byte or field to be processed; 
if omitted, the address is assumed to be in the fullword field 
TCANAME (for TYPE=PHONETIC) , TCACKFD (for TYPE=FVERIFY) , TCAFLD 
(for TYPE=DEEDIT), or TCABITF (for TYPE=BITSETON) . 

FIELDS= (symbolic address[ , symbolic address,...]) 

are the labels of fields defined within the internal fixed- 
format TIOA to which the input data is to be transferred. The 
fields must be named in order of increasing displacement from 
the start of the TIOA, and there must be a one— to-one 
correspondence between the field names in this macro 
instruction and the fields in the TIOA. The length of each 
field is determined by calculations based on the location 
represented by the symbolic address of the following field. 
Each field should be at least one byte in length. For 
positional input, each field for which data may be entered 
(that is, each position in the receiving area of storage) must 
be defined. 



FIELD 1 = 



specifies the characteristics of the search field to be 
compared against a corresponding field in records of the data . 
set on which the weighted retrieval function is to operate. 

symbolic address 

is the symbolic address of the field. If omitted, the 
address of the field is assumed to be in TCAWPA1, a four- 
byte field. 

numeric value 

is the length of the field in bytes and may range from 1 to 
32767. If omitted, the length of the field is assumed to 
be in TCAWPH1, a half word field. 

char 

is one character indicating the format of the data in the 
field as follows: 



Chara c ter Data Format 

C EBCDIC characters 

Z Zoned decimal numbers 

P Packed decimal numbers 

H Halfword binary <* 

F Fullword binary 

If this parameter is omitted, the character is assumed to 
be in TCAHPB1, a one— byte field. 

If one of these operand entries is omitted but succeeding 
operand entries follow, the comma that otherwise follows the 
entry must be included in the operand. 
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PIELD2= 



PTABLE= 



Not es; 

1. The application programmer must ensure that the integrity 
of FIBLD1 is not destroyed prior to the first DFHBIF 
TYPE=WTRETGET macro instruction. These values are used by 
the built— in functions program (DFHBPP) at that time. In 
particular, it is not advisable to utilize an area within a 
TIOA for this value. 

2. The largest decimal number that can be contained in a zoned 
decimal (Z) or packed decimal (P) field cannot exceed 16 
digits, including the sign. 



specifies the location of the data in the field of each record 
of the data set involved in the comparison with the search data 
in FIBLD1. 

symbolic address! 

is the symbolic address (label) of the first byte of the 
storage area that will contain the record to be examined. 
If omitted, the address of the main storage area is assumed 
to be in TCAWPA3, a four— byte field. 

symbolic address2 

is the symbolic address (label) of the field within the 
storage area identified by symbolic addressl to be used in 
the weighted retrieval comparison. If omitted, the address 
of the field is assumed to be in TCAWPA4, a four— byte 
field. 

If the first operand entry is omitted but the second is 
specified, the comma that otherwise follows the first entry 
must be included in the operand. 



is a description of the table from which a value is to be 
retrieved (the function table) . If no function value is to be 
retrieved (for example, if only the index of a matching 
argument table entry is needed) , this operand can be omitted. 
If this operand is specified, but some entries are omitted, the 
values of the corresponding entries in the ATABLE operand are 
assumed to apply. 

If a complex table (where each table entry contains both an 
argument and a function value) is being searched, the argument 
table and function table, as defined for this macro 
instruction, are actually within the same table in storage. 
Alternatively, two separate tables, one containing search 
fields and one containing function values, may be used. 

symbolic addressl or YES 

is the address of the first function table entry. If YES 
is specified, the address is assumed to be in TCATSA3, a 
fullword field. 

symbolic address2 or YES 

is the address of the function field within the first 
function table entry. If YES is specified, the address is 
assumed to be in TCATSA5, a fullword field. This address 
must be egual to or greater than symbolic addressl. If it 
is not, bit 5 of TCATSRPC is set on and no search is made. 
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numeric value 1 or YES 

is the length of each entry in the function table 
(including any other fields in the entry or slack bytes 
reguired for boundary alignment) . A value in the range 
from 1 through 32767 may be specified. If YES is 
specified, the value is assumed to be in TCATSH3, a 
halfword field. 

numeric value2 or YES 

is the length of the field to be retrieved from the 
function table. If YES is specified, the length is assumed 
to be in TCATSFF, a one— byte field. The length must be 
between 1 and 255 inclusive. If this operand is omitted, 
the default is the corresponding entry in the ATABLE, or 
its default if the corresponding entry is not specified in 
the ATABLE. The default for this operand is not numeric 
value 1 above. 

ILLOGIC=symbolic address 

specifies the entry label of the user— written routine to 
which control is to be passed if a VSAH error that does not 
fall within one of the other CICS/VS response categories 
occurs. 

INDEX=symbolic address 

specifies the address of a halfword field in which an index 
value relative to one, identifying the matching argument— table 
entry, is to be returned to the application program. In 
addition, the index value is placed in TCATSH4, a halfword 
field, whether or not the INDEX operand is specified. Both 
fields contain zero if no matching entry is found. 



INPOTNO= 



INPUTPC= 



specifies the maximum number of records that can be examined. 
A value from 1 to 32767 may be specified. 

symbolic address 

is the address of a halfword field that contains the 
maximum number of records that can be examined. 

numeric value 

is a decimal numeral indicating the maximum number of 
records that can be examined. 

YES 

indicates that the maximum number of records to be examined 
has been placed in TCAWTH1, a halfword field. 

If this operand is omitted, a default value of 512 is placed in 
TCAWTH1. 



specifies the percentages to be used by the weighted retrieval 
built— in function to determine the limits of acceptability. 

suboperandl 

specifies the maximum percentage, a value from to 100; 
this value can be indicated by the symbolic address of a 
halfword field containing the maximum value, a decimal 
numeral, or YES, which indicates that the value has been 
placed in TCAWTH3. If omitted, the maximum percentage is 
assumed to be 100* 
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suboperand2 

specifies the minimum percentage, a value from to 100; 
this value can be indicated by the symbolic address of a 
halfword field containing the minimum value, a decimal 
numeral, or YES, which indicates that the value has been 
placed in TCAWTH4. If omitted, the minimum percentage is 
assumed to be 0. 

If the first suboperand is omitted, but the second is 
specified, the comma that otherwise follows the first 
suboperand must be included. If only one suboperand is given, 
it is assumed to be the first suboperand (the maximum 
percentage, 100). 



INPUTST= 



indicates the number of records with the specified partial key 
to be skipped before examination of records begins. The 
maximum value that can be specified is 32767. 

symbolic address 

is the address of a halfword field that contains the 
relative numoer of the record that is to be examined first. 

numeric value 

is a decimal numeral indicating the relative number of the 
record that is to be examined first. 

YES 

indicates that the relative number of the desired record 
has been placed in TCAUTH2, a halfword field. 

If this operand is omitted, a default value of is placed in 
TCAWTH2. The weighted retrieval begins with the first record 
having the specified partial key. 

INVREQ=symbolic address 

specifies the entry label of the user— written routine to uhich 
control is to be passed if an invalid type of reguest is 
received. 

IOERROR=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an input/output error occurs. 

LABEL=symbolic address 

is the label to be assigned to the list of keywords. This 
label must be unigue within the application program and may be 
from one to eight characters in length. 



LENGTH= 



specifies the length of the field to be processed or the size 
of the TIOA to be acguired. 

symbolic address 

is the address of a halfword field that contains the length 
value . 
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MATCH= 



NAMES= 



numeric value 

is the length, in bytes, of the field to be processed, or 
the area to be acquired for the TIOA * 

The maximum length of a field is 32767 Dytes. The length of 
the TIOA must be sufficient to accomodate all fields specified 
in the FIELDS operand. 

If this operand is omitted, the length is assumed to be in the 
halfword field TCACKLN ((for TYPE=FVERIFY) , TCAFLN (for 
TYPE=DEEDIT) , or in TCAINH1 (for TYPE=INFORMAT) . 



specifies a value to be added to the current total counter if 
the comparison is performed and to the weighted counter if the 
compared fields are equal. The value may range from —32768 
through +32767. 

symbolic address 

is the symbolic address of a halfword field containing the 
value. 

numeric value 

is a decimal numeral in the range stated above. 

If this parameter is omitted, the value is assumed to be in 
TCAHPH2. 

Note : All match and no— match values specified for a weighted 
retrieval operation must have like signs. 



indicates that field names may be present as keywords in the 
input data stream. 

symbolic address 

is the LABEL parameter specified in a DFHBIF TYPE=DEFLDNM 
macro instruction in which the keywords that may be 
specified are defined. 

YES 

indicates that the label specified in the DFHBIF 
TYPE=DEFLDNM macro instruction defining the field names is 
in TCAINA2, a fullword field. 

(key word[ , keyword, ... ]) 

is a list of the Keywords that may be entered by the 
terminal user to indicate which fields are to receive input 
data. Each keyword may be from one to four characters in 
length. Any combination of alphabetic, numeric, and/or 
special characters may be specified. The keywords must be 
specified in the order in which the corresponding fields 
that will hold the data are defined in the fixed— format 
TIOA. 



NOMATCH= 



specifies a value to be used during weighted retrieval, or the 
address to which control is to be passed if matching is 
unsuccessful. 
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symbolic address 

is the symbolic address of a halfword field containing the 
value to be subtracted from the weighted counter if the 
compared fields are not egual, or it is the address to 
which control is to be passed if no table entry matching 
the search argument is found. 

numeric value 

is a decimal numeral in the range —327 68 through +32767. 

If this parameter is omitted, the value is assumed to be in 
TCAHPH3. 

N ote ; All match and no— match values specified for a weighted 
retrieval operation must have like signs. 

If this operand is specified, the SOBST operand cannot be 
specified. 

NORESP=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if no error occurs. NORESP signifies 
"normal response". 

NOTFND=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an attempt at weighted retrieval is 
unsuccessful. NOTFND signifies "record not found". 

NOTOPEN-symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if the requested data set is not open. 



NRECDS= 



NULL= 



indicates the maximum number of records to be made available to 
the application program. A value from 1 to 32767 can be 
specified. 

symbolic address 

is the address of a halfword field that contains the 
maximum number of records. 

numeric value 

is a decimal numeral indicating the maximum number of 
records. 

YES 

indicates that the maximum number has been placed in 
TCAWGCNT, a halfword field. 

If this operand is omitted, a default value of 200 is assumed. 



specifies a one— byte "null character" which, if present in 
either FIELD 1 or FIELD2, indicates that no comparison is to be 
performed . 

symbolic address 

is the symbolic address of a one— byte field containing the 
null character. 
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character value 

is a single EBCDIC character within single quotation marks. 

YES 

indicates that the null character has been placed in 
TCAWPNL, a one-byte field. 

The null character cannot be a binary zero (that is, X^O 1 ); 
such a specification is ignored. 

NUMERIC=symbolic address 

is the address to which control is to be passed if the field 
consists entirely of EBCDIC numbers (X'FO 1 through X , F9') with 
an optional trailing minus sign or •CR». 

OFLOW=symbolic address 

specifies the entry label of the user— written routine to which 
control is to be passed if an overflow condition occurs. 

ORDER= 

describes the sequence used in ordering the entries of the 
argument table and is optional if RANGE is not specified. The 
seguence must be EBCDIC; packed, fullword and half word binary, 
and floating— point tables cannot £>e searched. When this 
parameter is specified, a quick binary search is used (rather 
than a sequential search) . 

ASCENDING 

indicates that table entries are organized in ascending 
order according to the entries in the field to be compared 
with the search argument. 

DESCENDING 

indicates that table entries are organized in descending 
order according to the entries in the field to be compared 
with the search argument. 

In either case, the field values are interpreted as EBCDIC 
representations. If this operand is not specified, the 
argument table is assumed to be unordered and is searched 
sequentially, starting at the last entry of the table. 

PACKED=symbolic address 

is the address to which control is to be passed if the field 
consists entirely of packed decimal characters, that is, of 
half— bytes with hexadecimal values in the range through 9, 
except for the rightmost half— byte, which must contain a 
hexadecimal value in the range A through P. 

RANGE=YES 

is an optional operand indicating that, if no field compared 
with the search argument is an exact match, an existing table 
entry that would be adjacent to such an entry is to be taken as 
the function value. When this operand is specified, ORDER must 
be specified; otherwise, a sequential search of the table is 
made, starting at the last entry. 



RANGE= 



indicates that the compared fields are to be considered egual 
if FIELD2 falls within a given range of FIELD1. 
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suboperandl 

specifies the type of range used in the comparison. This 
entry can be a single character or YES, which indicates 
that the single character specifying type has been placed 
in TCAWPTR. The valid characters are as follows: 



Character Type of Range 



P Percentage 

U Units 

V Value 



suboperand2 

specifies the upper limit, exceeding the value in FIELD1, 
which is to be considered a match. This entry can be a 
positive numeric value up to 32767 or YES, which indicates 
that the upper limit has been placed in TCAWPH4. 

suboperand3 

specifies the lower limit, below the value in PIELD1, which 
is to be considered a match. This entry can be a positive 
numeric value up to 32767 or YES, which indicates that the 
lower limit has been placed in TCAWPH5. 

If suboperand3 is omitted, suboperand2 is assumed to apply both 
above and below the value in FIELDS For example, if the value 
in FIELD1 is 165 and RANGE=(U,5) is specified, then any value 
from 160 through 170 is considered a match. If RANGE= (U,5, 10) 
is specified, then any value between 155 and 170 is considered 
a match. If RANGE=(P,20) is specified, then any value between 
132 and 198 {165* (1±20%) } is acceptable. If RANGE= (V, 190, 160) , 
then any value between 160 and 190 is acceptable. If the data 
field contains EBCDIC characters (that is, C is specified in 
the FIELD1 operand), the RANGE operand is ignored. 

Not e: The upper bound and lower bound values are computed 
using the following formulas (where K is the value of FIELD 1) : 

1. For P— type range, specified (P,x,y) or (P,x): 



OB = K * (1 + x/100) UB = K * (1 + x/100) 

or 
LB = K * (1 - y/100) LB = K * (1 - x/100) 

2. For U— type range, specified (U,x,y) or (D,x) : 

UB=K+x UB=K+x 

or 
LB = K - y LB = K - X 

3. For V— type range, specified (V,x,y) : 

UB = x 
LB = y 
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RDIDADR=symbolic address 

is the symbolic address of the record identification field that 
contains the partial key of the record at which the data set is 
to be positioned prior to the retrieval process; if omitted, 
the address is assumed to be in TCAWTRI, a fullword field. 
(The format of the record identification field for a VSAM data 
set is described under "Record Identification Field" in Chapter 
3.1.) 

SUBST= 

specifies a value to be stored in TARGET if no entry matching 
the search argument is found in the argument table. 

symbolic address 

is the address of a field that contains the value to be 
stored. 

■literal value' 

is the value to be stored; single guotation marks must 
enclose the value in this specification but are not stored 
as part of the data. 

If this operand is specified, the TARGET operand must be 
specified, and the NOMATCH operand cannot be specified. 

TARGET=symbolic address 

is the symbolic address of the field in which the built— in 
function value is to be returned to the application program. 
The address of the function value is placed in TCATSA5, a 
fullword field, regardless of whether TARGET is specified. 
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Part 7. Error Handling and Debugging 
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Chapter 7.1. Introduction to Error Handling and Debugging 



A number of aids to testing, monitoring, and debugging are provided by 
CICS/VS, as follows: 

* Seguential Terminal Support — provides a method in which sequential 
devices, such as a card reader or disk: unit, can be made to 
simulate the online interactive terminals or subsystems of a 
CICS/VS network. This enables early testing to be carried out 
without the need for remote terminals or subsystems in the network 
to be active. Sequential terminal support is described in Chapter 
7.2. 



en 



Trace Management — provides a trace table containing entries that 
reflect the execution of CICS/VS macro instructions by user— writt 
application programs and by CICS/VS management programs. The trace 
table can be stored also in auxiliary storage on a sequential 
device through the CICS/VS Auxiliary Trace facility. The trace 
table and the DFHTR macro instruction by which it is invoked are 
described in Chapter 7.3. 

Dump Management — provides a dump of main storage that can be 
analysed to locate errors in application programs or in CICS/VS. 
Areas of main storage can oe dumped onto a sequential data set, 
either tape or disk, for subsequent offline formatting and printing 
by a CICS/VS utility program. The types of dumps and the DFHDC 
macro instruction that produces them are described in Chapter 7.4. 

Journal Management — provides a journal or log of the real— time 
activity that occurs during the execution of the CICS/VS system. 
This journal is stored in a sequential data set and the information 
it contains is essential for the reconstruction of that real— time 
activity. The contents of a journal, and the DFHJC macro 
instruction used to control these contents, are described in 
Chapter 7.5. 

Recovery/Restart (Sync Point) Management — provides for the 
emergency restart of CICS/VS after it has terminated abnormally and 
also allows for erroneous operations to be backed out. The setting 
up of the sync points and the DFHSP macro instruction used to do 
this are described in Chapter 7.6. 



Chapter 7.1. Introduction to Error Handling and Debugging 499 



Chapter 7.2. Sequential Terminal Support 



Even at the simplest level of program testing, the implementer faces 
problems. It is not efficient to test a program from a terminal if all 
test data must be keyed into the system from that terminal for each test 
shot. The programmer cannot easily retain a backlog of proven test data 
and quickly test programs through the key— driven terminal as changes are 
made. There is also the risk that a fault developing in a test 
procedure being used in an operational system could affect the whole 
system. 

CICS/VS allows the application programmer to begin testing programs 
without the use of a telecommunication device . It is possible to 
specify through the terminal control table that sequential devices be 
used as terminals. These sequential devices may be card readers, line 
printers, disk units, or magnetic tape units. In fact, a terminal 
control table can include combinations of sequential devices such as: 
card reader and line printer, one or more disk or tape data sets as 
input, one or more disk or tape data sets as output. A table that 
contains references to these card— reader— in/line— printer-out (CRLP) 
terminals can also include references to other terminals on the system. 

The input data submitted from a sequential device must be prepared in 
the form that it would come from a telecommunications device. A one— to 
four— character transaction identification only, or if data is included, 
a one— to four-character transaction identification (followed by a 
system— defined transaction code delimiter or a blank if less than four) 
must appear in the first one to four positions of the first input for a 
transaction. If a sequential device is being used as a terminal, an 
end— of— data indicator, a 0-2—8 punched card code (X^EO 1 ) or the 
equivalent as specified at system generation, must follow the input 
message or the system— defined data termination character. The input is 
processed sequentially and must be unblocked. The Sequential Access 
Method (SAM) is used to read and write the necessary inputs and outputs. 
The operating system utilities can be used to create the input data sets 
and print the output data sets. 

Using this approach, it is possible to prepare a stream of 
transaction test cases to do the basic testing of a program module. As 
testing progresses, the user can generate additional transaction streams 
to validate the multiprogramming capabilities of his programs or to 
allow transaction test cases to be run concurrently. 

At some point in testing, it is necessary to use telecommunication 
devices to ensure that the transaction formats are satisfactory, the 
terminal operational approach is satisfactory, and the transactions can 
be processed on the terminal. The terminal control table can be altered 
to contain more and different devices as the testing requirements 
change. 

When the testing has proven that transactions can be processed 
concurrently and the necessary data sets (actual or duplicate) for 
online operation have been created, the user begins testing in a 
controlled environment with the telecommunication devices. In this 
environment, the transaction test cases should represent all functions 
of the eventual system, but on a smaller, measurable scale. For 
example, a company whose information system will work with 15 district 
offices may select one district office for the controlled test, during 
which all transactions, data set activity, and output activity from the 
system should be measured closely. 
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Requests for input or output from a sequential terminal are specified 
in terminal control macro instructions (DFHTC) , just as other requests 
for input/output operations. 

In response to a DFHTC TYPE=READ, where the terminal has been 

described in the terminal control table as a CRLP, DISK, or TAPE 

terminal, data is read from the input data set until any of the 
following occurs: 

• An end-of-data indicator is detected in the input stream. (The 
indicator must be defined by the user at system generation time.) 

• Sufficient input has been read to fill the input area associated 
with the line used for transmission. If an end— of-data indicator 
is not detected before the input area is filled, all further data 
preceding an end-of— data indicator is bypassed and treated as a 
system error, which is passed to the user— installation terminal 
error program (DFHTEP) . 

© End of file (EOF) is detected. The READ is considered complete. 
Any subsequent READ is treated as a system error, which is passed 
to the user— installation terminal error program (DFHTEP) with a 
response code of 4. (Under CICS/DOS/VS, EOF applies to a card 
reader only.) 

In response to a DFHTC TYPE=WRITE from a CRLP terminal, multiple 
lines are written in print format as follows: 

• If there is no new— line (XM5 1 ) character within the number of 
characters contained in one print line of the specified line size 

(as found in TCTTELPL, a field in the TCTTE), the output is written 
in fixed— length lines of the size specified. 

© If new— line characters are encountered, a new line is begun for 
each. Writing of output continues until the end of the terminal 
input /output area (TIOA) is reached. 

For additional information about the DFHTC macro instruction, see 
Chapter 4.2. 
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Chapter 7.3. Trace Control (DFHTR Macro) 



The CICS/VS trace facility is a debugging aid for application 
programmers and IBM field engineers. It maintains in main storage a 
trace table consisting of standard CICS/VS entries and entries defined 
by the user. The table is filled in a wrap-around manner: when it is 
full, subsequent entries begin to overwrite the entries at the beginning 
of the table. 

Tracing can be activated and deactivated by a DFHTR macro instruction 
in an application program or by the master terminal transaction CAST. 
The macro instruction can also be used to specify the events to be 
recorded in the table. 

The trace entries can also be stored in auxiliary storage on a 
sequential data set, as well as recorded in the trace table, by the 
CICS/VS auxiliary trace facility, which is activated and deactivated 
only by the the master terminal transaction CSMT. The auxiliary— trace 
data set does not wrap around: all entries are preserved so that a 
complete history is obtained. The CICS/VS trace utility program 
(DFHTUP) , the use of which is described in the C ICS/V S Syst em 
Prog rammer's Guides , can be used to print the contents of the auxiliary- 
trace data set or selected entries from it. 

Standard entries can be recorded in the trace table each time one of 
the following macro instructions is issued by an application program or 
| by a CICS/VS management or service program. (This list does not cover 
| all entries; refer to the CICS/VS Proble m Determ i nation Guid e for 
| further details.) 

DFHKC (Task Control) 

DFHSC (Storage Control) 

DFHPC (Program Control) 

DFHIC (Interval Control) 

DFHDC pump Control) 

DFHFC (File Control) 

DFHTD (Transient Data Control) 

DFHTS (Temporary Storage Control) 

DFHJC (Journal Control) 

DFHBMS (Basic Mapping Support) 

DFH3IF (Built-in Functions) 

DFHTC (Terminal Control for VTAM-supported terminals only) 

DFHSP (Sync Point Program) 

DFHDI (Data Interchange Program) 

CICS/VS-DL/I Interface (OS only) 
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In addition to these standard entries, other entries produced by the 
terminal abnormal condition program can be recorded in the trace table. 
These entries, termed field engineering (FE) entries, are normally 
inhibited but can be activated by the DFHTE macro instruction. 

A third class of entry, the user entry, can be defined by the 
application programmer with the DFHTR macro instruction. 

Trace control is branched to by the reguesting program and executes 
as a service routine under the TCA of the reguesting program. Registers 
are saved and restored. Return after the reguested service has been 
performed is to the next seguential instruction in the reguesting 
program. 



Trace Table 

The CICS/VS trace table consists of a trace header and a number of 
fixed— length entries that can be used to trace the flow of transactions 
through the system. Assuming that the trace program has been generated, 
the trace table will be built during system initialization if the number 
of entries specified in the TRP parameter of the DFHSIT system macro is 
other than zero. 

The trace table can be initially disabled by specifying OFF in the 
TRP parameter. The master terminal can be used to turn trace or 
auxiliary trace on or off during CICS/VS execution. If a nonzero number 
of entries in the trace table is specified, the address of the trace 
header is placed at CSATRTBA. 

The address of the trace table header is held in field CSATRTBA 
(contents of R 13 plus X»11C«). 

Each entry in the trace table is 16 bytes in length and aligned on a 
double— doubleword boundary. The table is used in a wraparound manner so 
that when the last entry is used, the next entry is placed at the 
oeginning of the table. The first three words of the trace table 
contain "HEADER AT" and the fourth word contains the address of the 
trace header. The trace header format is: 

Bytes C onten ts 

0—3 Address of the last-used entry 

4—7 Address of the beginning of the table 

8—11 Address of the end of the table 

12—15 Reserved 

The format of an entry in the trace table is: 

Bytes Conten ts 

Trace identification of entry. 

See "Trace Identification" later in this Chapter. 

1-3 If byte contains other than one of the values from 

X»F0» througn X*FC», these bytes contain the contents of 
register 14 at entry to the trace control program. 
If byte contains a value from X , F0 t through X'FC, 
these bytes contain the contents of register 14 at entry 
to the CICS/VS management or service program involved. 

4 and 5 For user entries, these bytes are unused. 
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(bits 0—3) If byte contains one of the values from X'YQ 9 through 
X»FC« or X^CS 1 through X^ 1 , these bytes generally 
contain the type of reguest code as it relates to the 
CICS/VS management or service program involved as 
follows: 



Program 

Task control 

Storage Control 

Program control 

Interval control 

Dump control 

File control 

Transient data control 

Temporary storage control 

CICS/VS-DL/I interface 

Journal control 

Basic mapping support 

Built-in functions 

Terminal control 

Sync point 

Data interchange 

Trace control 

Dynamic transaction backout 

EXEC interface 

Field Engineering 

User exit interface 



Trace 

Identif icatior 


L 


X 


»F0« 


,X«D0» 




X 


»F1' 


'^•ce'^' 


C9»,X»CA» 


X 


»F2' 






X 


'F3' 






X 


»F4« 






X 


•F5 






X 


»F6' 






X 


»F7' 






X 


»F8' 






X 


■F9' 






X 


•FA 


•^•CD^X' 


CF« 


X 


»PB« 






X 


»FC 






X 


•D8 






X 


•D7 






X 


»FD 


',X«FE»,X' 


FF« 


X 


'CB' 






X 


■El' 






X 
X 


•E6 
'D5 


' through 


X»EF» 



Indicate the type of entry, as follows: 



(bits 4-7) 




X«0' 


1 Reserved 


X»1' 


' FE entry 


X»2' 


User entry 


X»3 


LIFO system entry 


X»4' 


System entry 


X»5 


1 LIFO response/return 


X«6 


1 Reserved 


X«7' 


1 Reserved 



X»8» 


Reserved 


X»9» 


Reserved 


X»A« 


Reserved 


X»B» 


Reserved 


X»C» 


Reserved 


X»D» 


On/off entry 


X»E» 


Aux trace entry 


X«F* 


Extended entry 



6-7 



8-11 



Transaction identification as found in TCAKCTTA, a field 
in the system section of the TCA. This identification is 
either a user task sequence number from 1 to 9999, 
assigned by CICS/VS and stored in packed decimal form in 
the rightmost (low— order) bytes, or the system task 
identification (KC for task control, TC for terminal 
control, or JC for journal control) stored in the 
leftmost bytes. 

Data field A. 



12-15 



Data field B. 



The contents of byte and the two data fields (bytes 8 through 15) 
of application program— reguested entries are determined by the DFHTR 
TYPE=ENTRY macro instruction. 

The contents of trace table entries for CICS/VS programs are fully 
described in the CICS /VS P roblem Determi nation Guide. 

If consecutive, identical entries are generated, the first entry only 
is entered into the table. In these cases ; a special trace control 
entry with trace identification X'FD* is created, and a count of the 
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number of times the previous entry is repeated is stored therein. Trace 
control entries with trace identification X^FE 1 or X^F 1 indicate the 
turning on or turning off of the trace facility, respectively. 

Some of the functions required for recovery/restart as available 
under CICS/OS/VS are performed by the sync point program. The trace 
table entry for this program is described in Figure 8.B— 16. 

An entry with a trace identification in the range from X'ES* through 
X^EF 1 is a special Field Engineering (FE) entry. The trace 
identification X'ES* is included in all entries produced by the terminal 
abnormal condition program. The contents and format of these entries 
are described in the CICS/VS Problem Determination Guide . 

If the entry is written to the auxiliary— trace data set, a 4— byte 
prefix is appended to the entry. This prefix contains the time that the 
entry was written to that data set. Auxiliary trace writes the time, to 
the data set, in units of 128 microseconds. The trace utility programs 
convert this time to hours: minutes: seconds: microseconds, when 
formatting the auxiliary trace output. 

The contents of any fields characterized as "Not used" in the 
descriptions should be ignored during the analysis of a trace table 
entry. 



T race Identificatio n 

Each standard entry contains in byte zero a unigue trace identification 
from 240 through (X^FO 1 through X^OO 8 ) and information to aid the 
application programmer in determining where the macro instruction was 
issued and what type of request was made to the management program. 

The application programmer can make direct, nonstandard entries in 
the trace table by using the DFHTR macro instruction. A trace 
identification number from through 199 (X^O* through X'C? 1 ) and 
accompanying data is assigned for each trace entry. Thus, by defining 
several unigue trace entries, the programmer can trace the logical path 
through a particular application or group of application programs. 



Controlling the Trace 

The trace control macro instruction DFHTR is used to activate and 
deactivate tracing, and to insert user-defined entries in the trace 
table. The trace can be activated and deactivated for the entire 
CICS/VS system or for the issuing task alone. 

The tracing facility can be controlled at various levels, as follows: 

1. Master trace control 

2. System, FE, or user control 

3. (a) Within System, class control 
(b) With User, single task control 

To make a user trace entry, the master trace control flag must be on, 
together with either the user control flag on or the single task trace 
flag on. The first is accomplished by issuing DFHTR TYPE=ON, 
STYPE=USER; the second is done by DFHTR TYPE=0N, STYPE=SINGLE. 
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To activate all tracing functions, issue 
DFHTR TYPE=ON, STYPE=ALL 

To activate system trace entries only, issue 
DFHTR TYPE=ON, STYPE=SYSTEM followed by 
DFHTR TYPE=ON, STYPE= (appropriate class name) 

or use 

DFHTR TYPE=ON, STYPE=ALL as above. 



Tracing of eacn event specified in a DFHTR TYPE=ON macro instruction 
continues until terminated by a DFHTR TYPE=OFF macro instruction. The 
STYPE operand in the DFHTR TYPE=OFF macro instruction specifies which 
events are no longer to be logged. 

The STYPE operand of the DFHTR macro instruction is used to specify 
whether the instruction applies to the entire CICS/VS system or only to 
the issuing task (SINGLE and SYSTEM parameters) . 

The application programmer can use the DFHTR TYPE=ENTRY macro 
instruction to place his own entries in the trace table. 

The following example illustrates how to activate the trace facility 
for the issuing task and then to initiate tracing for all classes of 
event except FE. It also shows how to suppress tracing of user entries 
and finally to deactivate the trace facility. 



DFHTR TYPE=ON,STYPE=SINGLE 



DFHTR TYPE=ON,STYPE=ALL 



DFHTR TYPE=OFF,STYPE=USER 



ACTIVATE TRACE FOR THIS TASK 



START LOGGING ALL CLASSES EXCEPT FE 



STOP LOGGING USER ENTRIES 



DFHTR TYPE=OFF,STYPE=SINGLE DEACTIVATE TRACE 



Initiate Trace (TYPE=ON) 



The format of the DFHTR macro instruction to start logging entries into 
the trace table is as follows: 



DFHTR | TYPE=ON 

| [ ,STYPE= {SINGLE | ALL | (system syrabol1[ ,sys 
| SYSTEM | USER | FE) ] 



•]) I 
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Terminate Trace (TYPE=OFF) 



The format of the DFHTR macro instruction to stop logging entries into 
the trace table is as follows: 



I 

DFHTR | TYPE=OFF 

| [ ,STYPE= {SINGLE |ALL| (system symbol 1[ ,sys ...]) | 
| SYSTEM I USER I FBI ] 

I 

i 



Selected Entry Trace (TYPE=ENTRY) 



The format of the DFHTR macro instruction to cause a given entry to be 
logged is as follows: 




TYPE=ENTRY 

[ ,STYPE= {SYSTEM I USER 1FE} ] 

,ID=number 

[ , DATA 1= {symbol | (symbol)} ] 

[ ,RD ATA 1= {register | (register)} ] 

[ ,DATA2= {symbol | (symbol)} ] 

[ ,RDATA2= {register | (register)} ] 

[ ,DATA1TP={HBIN|FBIN| CHAR | PACK | POINTER} ] 

[ ,DATA2TP={HBIN|FBIN|CHAR| PACK | POINTER} ] 
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Operands of DFHTR Macro 



DATA1= 



DATA1TP= 



specifies the address of the data to be placed in the first 
data field (bytes 8 to 11) of the trace table entry. 

symbol 

is the symbolic address of the data to be placed in the 
first data field of the table entry. 

(symbol) 

is the symbolic address of an area that contains the 
address of the data to be placed in the first data field. 

When this operand is included in a high— level language program, 
DATA1TP is reguired. 



specifies the format of the data to be placed in the first data 
field of the trace table entry. The meanings of the keyword 
parameters are as stated below: 



Specification Data Format 
DATA1TP=HBIN Halfword, binary 



DATA1TP=FBIN 



DATA1TP=CHAR 



DATA1TP=PACK 



DATA1TP=P0INTER 



Full word, binary 



1 to 4 characters 



1 to 4 bytes, 
packed decimal 

PL/I pointer 
variable 



Field Definition 

COBOL: 9 (4) CO MP 
PL/I: BIN FIXED (15) 

COBOL: 9(8) COUP 
PL/I: BIN FIXED (31) 

COBOL: X (4) 
PL/I: CHAR (4) 

COBOL: 9 (7) COMP-3 
PL/I: DEC FIXED (7) 

PL/I: POINTER 



This operand is valid only for COBOL 
omitted, the default is FBIN. 



and PL/I programs. If 



DATA2= 



DATA2TP= 



is similar to DATA1 except that it is used for the second data 
field (bytes 12 to 15) of the trace table entry. 

When this operand is included in a high— level language program, 
DATA2TP is reguired. 



is similar to DATA1TP except that it is used for the second 
data field of the trace table entry. 
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ID=number 

specifies the trace identification number for this entry and 
must be coded as a self— defining term. A number from through 
199 may be specified when STYPE=USER; a number from 200 through 
229 may be specified when STYPE=SYSTEM; and a number from 230 
through 239 may be specified when STYPE=FE. (The number 230 is 
included in all entries produced by the terminal abnormal 
condition program.) Numbers 240 through 253 (X^O 1 through 
X'FD 1 ) are reserved for system macro instruction trace entries. 
The numbars 254 (X«FE») and 255 (X»FF«) indicate TYPE=0N and 
TYPE=0FF entries, respectively. 

RDATA1= (Assembler— language programs only) 

specifies the register whose contents are to be placed in the 
first data field of the trace table entry. 

register 

the number of the register whose contents are to be placed 
in the first data field. 

(register) 

the number of the register whose contents are the address 
of the data to be placed in the first data field. 

RDATA2= (Assembler— language programs only) 

is similar to RDATA1 except that it is used for the second data 
field of the trace table entry. 



STYPE= 



indicates the type of entries to be logged or for which logging 
is to ba discontinued. If this operand is omitted, USER is 
assumed. 

SINGLE 

when included in the DFHTR TYPE=0N macro, specifies that 
the tracing of user entries is to be turned on for the task 
issuing the macro for the duration of the task or until 
turned off by a DFHTR TYPE=0FF, STYPE=SINGLE macro. 

when included in the DFHTR TYPE=OFF macro, specifies that 
the tracing of user entries is to be turned off for the 
task issuing the macro. 



ALL 

specifies that all tracing facilities (except Field 
Engineering) are to be turned on. This parameter turns on 
the master system trace flag and all of the individual 
system trace flags, in addition to performing the function 
of the USER parameter. It also, when used in the DFHTR 
TYPE=0FF macro, specifies that all tracing facilities 
(including Field Engineering) are to be stopped. 

(system symbol1[ ,sys . . . ]) 

specifies one or more system symbols that turn on or off 
appropriate system macro trace facilities. The valid 
system symbols are as follows: 
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Sym bol Meaning 

KC Task Control (DFHKC) 

SC Storage Control (DFHSC) 

PC Program Control (DFHPC) 

IC Interval Control (DFHIC) 

DC Dump Control (DFHDC) 

FC File Control (DFHFC) 

TD Transient Data Control (DFHTD) 

TS Temporary Storage Control (DFHTS) 

JC Journal Control (DFHJC) 

BM Basic Mapping Support (DFHBMS) 

BF Built-in Functions (DFHBIF) 

TC Terminal Control (DFHTC) (for VTAM-supported 

terminals only) 

SP Sync Point Control (DFHSP) 

DI Data Interchange Control (DFHDI) 

UE User Exit Interface 

For TYPE=ON, each symbol turns on a single system trace 
flag. Before tracing of any system macros occurs, the 
master system trace flag must also be turned on by means of 
the SYSTEM parameter. Note that two DFHTR macros must be 
issued to accomplish this; SYSTEM and system symbols cannot 
both be specified on the same macro. 

SYSTEM 

specifies that the entry is a CICS/VS entry. This 
parameter turns on or off the system master trace flag, 
which must be on in addition to the individual system trace 
flags before tracing of any system macros occurs. When 
used to turn off the master trace flag it does not turn off 
the individual system trace flags. See also the 
description of the system symbols above. Therefore, 
although all tracing activities for the system macros are 
suppressed, the previous pattern of activity could be 
reinstated by issuing a DFHTR TYPE=ON,STYPE=SYSTEM macro 
instruction, without the need to issue a DFflTR TYPE=ON 
macro with the various system symbols defined. 

USER 

specifies that the entry is a user entry and that when 
included in a DFHTR TYPE=ON macro specifies that the trace 
facility is to be turned on for all user entries for all 
active tasks; that is, causes the trace facility to begin 
logging user entries to the trace table for all tasks 
currently active in the system, and for all tasks becoming 
active subsequently, until the user trace facility is 
turned off. 

FE (Assembler— language programs only) 

specifies that the entry is a Field Engineering (FE) entry. 
This is the only parameter that will turn on the FE tracing 
facilities. 
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Dump management provides the capability of dumping specified areas of 
main storage onto a sequential data set, either tape or disk. This data 
set contains information about the user's transaction or application 
program, and can be subsequently formatted and printed offline (or while 
the dump data set is closed) using a CICS/VS dump utility program 
(DFHDUP) . 

Requests for dump services are communicated to dump control through 
the DFHDC macro instruction. A CICS/VS Snap dump can also be requested 
by the master terminal operator. Dump control executes at the priority 
of the requesting program, under control of the TCA of the requesting 
program saving and restoring registers from this TCA. After a requested 
dump service has been provided, control is returned to the next 
executable instruction in the requesting program. 

Dump control operates as a serially reusable program resource. Only 
one service request is processed at a time. If additional requests for 
dump services are made while a dump is in progress, the tasks associated 
with those service requests are delayed (suspended) and placed in a 
"hold" status until the dump is completed. Remaining dump requests are 
serviced on a first— in first— out (FIFO) basis. 

The dump management macro instruction (DFHDC) is used to request any 
of the following services: 

• Dump main storage areas related to a transaction and its associated 
task (or any other main storage areas) 

• Dump the following CICS/VS control taoles: program control table 

(PCT ) , processing program table (PPT), system initialization table 
(SIT) , terminal control table (TCT) , file control table (FCT) , and. 
destination control table (DCT) 

• Dump transaction-oriented storage areas and CICS/VS control tables 

• Dump selected main storage areas. 

• For CICS/OS/VS only, dump DL/I control blocks. 

To ensure a dump of the TIOA following a terminal control write that 
precedes a DFHDC macro instruction, the application programmer must 
issue a SAVE and WAIT with the DFHTC TYPE=WRITE macro instruction. 

When the DFHDC macro instruction is executed, information is stored 
in fields TCADCTR and TCADCDC of the common communication area of the 
TCA, which is used for CICS/VS service requests. Before doing so, 
however, the macro preserves the previous contents of the fields by 
copying TCADCTR (2 bytes) to TCACCSV1, and TCADCDC (4 bytes) to 
TCACCSV2. The previous contents can therefore be seen in the dump. The 
field TCADCDC is saved only if DHPCODE=value is specified. If 
DMPCODE=YES is specified, the user must preserve the contents of TCADCDC 
(if they are to appear in the dump) before storing the dump code in that 
field. 

The Dump Control module will use the register save area, TCACCRS, of 
the common communication area. To see the previous contents in a dump 
the application program must obtain 14 words of storage into which to 
copy the contents of TCACCRS before issuing the DFHDC macro. 
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CICS/VS control tables will be dumped only if the CICSDMP=YBS operand 
is specified in the DFHSG PROGRAM=DCP macro instruction at system 
generation. (See the CICS/VS System Programmer's Reference Manual . ) 

Every dump request will include the TCA, CSA, and trace table, unless 
one or more of these are suppressed with the SUPPR operand. The trace 
table will also be suppressed if the trace facility is not currently 
active. 
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Dump Transaction Storage (TYPE = TRANSACTION) 

The format of the DFHDC macro instruction to specify a dump is as 
follows: 



DFHDC | TYPE=TRANSACTION 

| [ ,DMPCODE= {value | YES} ] 

| [ ,SUPPR= ([CSA][ ,TCA][ ,TRT]) | ALL] 



This macro specifies a dump of all main storage areas related to a 
transaction and its associated task. This dump is normally used during 
the testing and debugging of user— written application programs. 
(CICS/VS automatically provides this service if the related task is 
abnormally terminated.) 

For CICS/OS/VS only, DL/I control blocks will also be dumped. The 
following main storage areas can be dumped: 

1. Task control area (TCA) and, if applicable, the transaction work 
area (TWA) 

2. Common system area (CSA) , including the user's portion of the C5ft 

(CWA ) 

3 . Trace table 

4. Contents of general— purpose registers upon entry to dump control 
from requesting task 

5. Either the terminal control table terminal entry (TCTTE) or the 
destination control table entry associated with the requesting task 

6. All transaction storage areas chained off the TCA storage 
accounting field 

7. All program storage areas containing user— written application 
program (s) active on behalf of the requesting task 

8. Register save areas (RSAs) indicated by the RSA chain off the TCA 

9. All terminal input/output areas (TIOAs) chained off the terminal 
control table terminal entry (TCTTE) for the terminal associated 
with the requesting task (if any) 

Whenever the TCTTE is dumped (see 5 above) , the terminal control 
■cable user area (if any) and the message control blocks (if any) 
associated with tne TCTTE are dumped. The latter are used by basic 
mapping support. 

The following example illustrates the coding required to request a 
dump of transaction storage: 

DFHDC TYPE=TRANSACTION, REQUEST TRANSACTION STORAGE DUMP * 
DMPCODE=D010 USER-SPECIFIED DUMP CODE 
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Dump CICS/VS Storage (TYPE=CICS) 

The format of the DFHDC macro instruction to specify a dump of system 
tables is : 



r 


i ■■■ i 

i i 




1 1 

DFHDC | TYPE=CICS | 
| [ ,DMPCODE= {value | YES} ] I 
| [ ,SUPPR= ([CSA][ ,TCA][ ,TRT]) |ALL] | 
1 1 


i 


1 I 
• » 



The application programmer can request a dump of PCT, PPT, TCT, FCT, 
and DCT by issuing the DFHDC TYPE=CICS macro instruction. This facility 
is available if the CICSDMP=YES operand is specified in the DFHSG 
PROGRAM=DCP macro instruction at system generation (see the CICS/VS 
Sy stem Programmer' s Refe r ence Manual ) . This dump is typically the first 
dump taken in a testing situation in which the base of the test must be 
established; subsequent dumps are usually of the TRANSACTION type. 

This macro specifies that PCT, PPT, SIT, TCT, FCT, and DCT are to be 
dumped. The TCA (and the TWA, if applicable) , CSA (and CWA) , and trace 
table are also dumped. 

The following example illustrates the coding required to request a 
dump of PCT, PPT, SIT, TCT, FCT, DCT, CSA, TCA, and the trace table: 

DFHDC TYPE=CICS, REQUEST CICS/VS STORAGE DUMP * 

DMPCODE=D020 USER-SPECIFIED DUMP CODE 
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Dump Transaction Storage and CICS/VS Storage (TYPE = COMPLETE) 

The format of the DFHDC macro instruction to specify a complete dump is: 



r i 

i 


DFHDC 


r ™ ,,...,,. — ..., 

1 

TYPE=COMPLETE | 

| [ ,DMPCODE= {value | YES} ] | 

| [ ,SUPPR=([CSA][ ,TCA][,TRT]) | ALL ] | 

1 1 
• « 



The application programmer can request a dump of both 
transaction/task-r elated storage and PCT, PPT, SIT, TCT, FCT , and DCT by 
issuing the DFHDC TYPE=COMPLETE macro instruction. The PCT, PPT, SIT, 
TCT, FCT, and DCT will be dumped if CICSDMP=YES was specified in the 
DFHSG PROGRAM=DCP macro instruction at system generation (see the 
CI CS/VS Syste m Pro g rammer's Reference Manual ). For CICS/OS/VS only, 
DL/I control blocks will also be dumped. 

To request a complete dump is sometimes appropriate during execution 
of a task, but this macro instruction should not be used excessively. 
CICS/VS control tables are primarily static areas; therefore, requesting 
one CICS dump and a number of TRANSACTION dumps is generally more 
efficient than requesting a comparable number of COMPLETE dumps. This 
macro specifies that transaction/tasK— related storage and PCT, PPT, SIT, 
TCT, FCT, and DCT are to be dumped. 

The following example illustrates the coding required to request a 
dump of both transaction storage and PCT, PPT, SIT, TCT, FCT, and DCT: 

DFHDC TYPE=COMPLETE, REQUEST COMPLETE STORAGE DUMP * 

DMPCODE=D030 USER-SPECIFIED DUMP CODE 



Chapter 7.4. Dump Control (DFHDC Macro) 517 



Dump Partial Storage (TYPE=PARTIAL) 

The format of the DFHDC macro instruction to specify a partial dump is: 



TYPE=PARTIAL 

,LIST= ([TERMINALS , PROGRAM ][ TRANSACTION ][ , SEGMENT ]) 

[ ,DMPCODE={value|YES} ] 

[ ,SUPPR= ([ CSA ][ ,TCA ][ ,TRT ]) | ALL ] 



The application programmer can request a dump of selected main 
storage araas related to the requesting task by issuing the DFHDC 
TYPE=PARTIAL macro instruction. This type of dump can be used during 
the testing and debugging of user— written application programs. It 
includes only the storage areas specified. 

If SEGMENT is specified in the LIST operand, the application 
programmer must code two instructions that place the address of the main 
storage area to be dumped into TCADCSA and the length (in binary) of the 
area to be dumped into TCADCNB prior to execution of the DFHDC 
TYPE=PARTIAL macro instruction. The maximum length that can be 
specified in TCADCNB is 32,767 bytes. The specified area must be a 
valid area, that is, storage allocated by the operating system within 
the CICS/VS region/partition boundaries. 

It is possible to dump several user areas rather than just one. The 
application programmer must construct a table of the user areas to be 
dumped, and their lengths, and place the address of the table in 
TCADCSA. Also, TCADCNB must be set to zero. Both of these actions must 
precede the DFHDC TYPE=PARTIAL macro. The table must consist of eight- 
byte entries, each entry containing a four— byte length field followed by 
a four— byte address field. The table should then be completed by adding 
an extra four— byte field containing X^FFFFFFFF 1 . 

The following example shows how to request a PARTIAL storage dump 
that includes, along with all program storage areas, all transaction 
storage areas associated with this task: 

DFHDC TYPE=PARTIAL, REQUEST PARTIAL STORAGE DUMP * 

LIST= (TRANSACTION, AREAS ASSOCIATED WITH TRANSACTION * 

PROGRAM), PROGRAM STORAGE AREAS * 

DMPC0DE=DT3P USER-SPECIFIED DUMP CODE 

This example is applicable to Assembler language, COBOL, or PL/I 
programs. All values passed to CICS/VS are specified in the DFHDC macro 
instruction. As noted above, when SEGMENT is specified, certain values 
must be stored in fields of the TCA prior to execution of the DFHDC 
macro instruction. The programmer can also store the dump code in the 
TCA prior to execution of the macro instruction. 

The following examples show how to request a PARTIAL dump of a 
selected main storage area, using either Assembler language, COBOL, or 
PL/I. 

F or A ss embler langua ge : 

ST R5, TCADCSA PLACE STORAGE ADDRESS IN TCA 

MVC TCADCNB, =H • 16384* PLACE LENGTH OF AREA IN TCA 
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MVC TCADCDC,=CL4•AB12 , 
DFHDC TYPE=PARTIAL, 

LIST=SEGMENT, 

DMPCODE=YES 



PLACE DUMP CODE IN TCA 
REQUEST PARTIAL STORAGE DUMP 
DUMP AREA PREVIOUSLY SPECIFIED 
DUMP CODE PREVIOUSLY SPECIFIED 



For COBOL : 



MOVE DATADDR TO TCADCSA. 
MOVE 16384 TO TCADCNB. 
MOVE 'AB12' TO TCADCDC* 
DFHDC TYPE=PARTIAL, 

LIST=SEGMENT, 

DMPCODE=YES 



MOTE PLACE STRG ADDRESS IN TCA. 
NOTE PLACE LENGTH OF AREA IN TCA 
NOTE PLACE DUMP CODE IN TCA. 
REQUEST PARTIAL STORAGE DUMP 
DUMP AREA PREVIOUSLY SPECIFIED 
DUMP CODE PREVIOUSLY SPECIFIED 



For PL/I : 



TCADCSA=ADDR (DATA ) ; 

TCADCNB=16384; 

TCADCDC=»AB12 I ; 

DFHDC TYPE=PARTIAL, 
LIST=SEGMENT, 
DMPCODE=YES 



/♦PLACE STORAGE ADDRESS IN TCA*/ 
/♦PLACE LENGTH OF AREA IN TCA*/ 
/♦PLACE DUMP CODE IN TCA*/ 
REQUEST PARTIAL STORAGE DUMP 
DUMP AREA PREVIOUSLY SPECIFIED 
DUMP CODE PREVIOUSLY SPECIFIED 
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Operands of DFHDC Macro 

DMPCODE= 



LIST= 



is a four-character dump code to be printed out with the 

requested dump to identify it; this code should be unique so 

that it is informative concerning the condition that caused the 
dump. 

value 

is a combination of four alphabetic or numeric characters 
to be printed as the dump code. 

YES 

indicates that the dump code has been placed in TCADCDC. 



identifies specific areas to be dumped. 

TERMINAL 

indicates that all storage areas associated with the 
terminal are to be dumped. These storage areas are as 
follows: 



1. Task control area (TCA) and, if applicable, the 
transaction work area (TWA) 

2. Common system area (GSA) , including the user»s portion 
of the CSA (CWA ) 

3. Trace table 

4. All terminal input/output areas (TIOAs) chained off the 
terminal control table terminal entry (TCTTE) for the 
terminal associated with the requesting task 

5. Contents of general— purpose registers upon entry to 
dump control from the requesting task 

6. Either the terminal control table terminal entry (TCTTE) 
or the destination control table entry associated 

with the requesting task 

Whenever the TCTTE is dumped, the terminal control table 
user area (if any) and the message control blocks (if any) 
associated with the TCTTE are dumped. The latter are used 
by basic mapping support. 

PROGRAM 

indicates that all program storage areas associated with 
this task are to be dumped. These storage areas include: 
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1. Task control area (TCA) and, if applicable, the 
transaction work area (TWA) 

2. Common system area (CSA), including the user's portion 
of the CSA (CWA) 

3. Trace table 

4. All program storage areas containing user— written 
application program (s) active on behalf of the requesting 
task 

5. Register save areas (RSAs) indicated by the RSA chain 
off the TCA 

6. Contents of general— purpose registers upon entry to 
dump control from the requesting task 

7. Either the terminal control table terminal entry (TCTTE) 
or the destination control table entry associated with 
the requesting task 

Whenever the TCTTE is dumped, the terminal control table 
user area (if any) and the message control blocks (if any) 
associated with the TCTTE are dumped. 

TRANSACTION 

is typically used in combination with other types of 
PARTIAL dump reguests to include all transaction storage 
areas associated with the task. These areas include: 



1. Task control area (TCA) and, if applicable, the 
transaction work area (TWA) 

2. Common system area (CSA), including the user , s portion 
of the CSA (CWA) 

3. Trace table 

4. Contents of general— purpose registers upon entry to 
dump control from the requesting task 

5. All transaction storage areas chained off the TCA 
storage accounting field 

6. Either the terminal control table terminal entry (TCTTE) 
or the destination control table entry associated 

with the requesting task 

7. DL/I control blocks (CICS/OS/VS only) 

Whenever the TCTTE is dumped, the terminal control table 
user area (if any) and the message control blocks (if any) 
associated with the TCTTE are dumped. 

SEGMENT 

is used to include in the PARTIAL dump any area of main 
storage specified. In addition to the selected area, the 
contents of the following storage areas are displayed: 
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SUPPR= 



1. Task control area (TCA) and, if applicable, the 
transaction work area (TWA) 

2. Common system area (CSA) , including the user^s portion 
of the CSA (CWA) 

3. Trace table 

4. Contents of general— purpose registers upon entry to 
dump control from the requesting task 

5. Either the terminal control table terminal entry (TCTTE) 
or the destination control table entry associated 

with the requesting task 

Whenever the TCTTE is dumped, the terminal control table 
user area (if any) and the message control blocks (if any) 
associated with the TCTTE are dumped. 

These parameters are not mutually exclusive. They can be 
specified in any combination and any order. The 
parentheses are optional when only one parameter is 
specified. At least one parameter is required. No storage 
area is dumped more than once as a result of a single DFHDC 
TYPE=PARTIAL request. Thus, for example, if DFHDC 
TYPE=PARTIAL,LIST= (TERMINAL, TRANSACTION) is specified, the 
contents of the TCA and CSA are displayed only once. 



indicates that one or more CICS control tables will not be 
dumped. The dumps to be suppressed are determined by coding 
one or more of the following: 



CSA Common system area 
TCA Task control area 
TRT Trace table 

These parameters are not mutually exclusive. They can be 
specified in any combination and any order. The parentheses 
are optional when only one parameter is specified, at least 
one parameter is required. Alternatively, all three of the 
above areas can be suppressed by coding SUPPR=ALL. 
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Journal management provides facilities for creating and managing 
special-purpose sequential data sets, called •journals, 1 during real- 
time CICS/VS execution. Journals may contain data the user needs to 
facilitate subsequent reconstruction of events or data changes. For 
example, a journal might act as an audit trail, a change— file of data- 
base updates and additions, or a record of transactions passing through 
the system (often called a •log 1 ). 

In addition to the output services described in this chapter, journal 
management also provides support for: 

• Operational control and disposition of volumes (see the C ICS/VS 
System Programmer's Guide (DOS/VS) or the C ICS/VS System 
Programm e r's Gui de (OS/VS) ) 

• Requests to switch volumes and/or read journal data sets during 
real-time CICS/VS execution (see the CICS/VS System Programmer's 
Reference Manual ) 

Requests for journal output services are made by issuing the journal 
control macro instruction (DFHJC) , either directly from a user task or 
from a CICS/VS management program on behalf of a user task. Data may be 
directed to any journal data set specified in the journal control table 
(JCT) , which defines the journals available during a particular CICS/VS 
execution. The JCT may define one or more journals on tape or direct 
access storage. Bach journal is identified by a number, in the range 2 
through 99, known as the journal file identification. The value of 1 is 
reserved for a journal known as the system log. 

All buffer space and other work areas needed for journal data set 
physical operations are acguired and managed by the journal control 
program (JCP). The user task supplies only the address and length of 
the data to be output* The data is moved to journal buffer space by JCP 
when building a journal record. The user task retains the use and 
control of the data and its CICS/VS storage area. 

Journal output requests are serviced by JCP. Journal records are 
built into blocks compatible with standard variable-blocked format. JCP 
uses the sequential access method of the host operating system to write 
the blocks to auxiliary storage. 

Each logical journal record begins with the standard four— byte length 
field, a user— specif ied identifier, and a system— supplied prefix. This 
data is followed in the journal record by any user— supplied prefix data 
(optional) , and finally by the user— specified data. Journal control is 
designed so that the application programmer requesting output services 
need not be concerned further with the detailed layout and precise 
contents of journal records. He needs to know only which journal to 
use, what user data to specify, and what unique user— identifier to 
supply. Normally, he obtains this information from the application 
system analyst or the person (s) responsible for programs for reading 
journal data sets. (See the CICS/VS System Programmer's Reference 
Manual .) 

JCP builds journal records for output requests at the priority of the 
requesting program, under control of the TCA of the requesting program. 
However, the TCA is not used to communicate requests and to save/restore 
registers. Instead, a separate control area called a journal control 



Chapter 7.5. Journal Control (DFHJC Macro) 523 



area (JCA) is used; this area roust be acquired by the task before any 
journal output requests are issued. 

If no other event is in— process to the journal, output to a journal 
data set is also initiated under the requestor's TCA. However, output 
event completion is always processed under a different TCA — that of a 
hiqh— priority journal task associated with the journal data set. 
Journal tasks are activated when CICS/VS execution beqins, but are 
suspended when there are no output events outstandinq. In a heavy load 
situation, where many user tasks request journal output while one output 
is in—process, a journal task initiates more output immediately after 
completion of the in— process output event. 

The application proqrammer may specify parameter values for journal 
control requests in either of two ways: 

• By includinq the parameters in operands of the DFHJC macro 
instruction by which journal services are requested, or 

• By codinq instructions that place the parameter values in fields of 
the JCA prior to issuinq the DFHJC macro instruction 

The second of these methods provides qreater economy, in that the 
parameter values can be varied to meet the loqic needs of the 
application, but only a sinqle DFHJC macro instruction need be coded. 

Journal output services that may be requested throuqh the journal 
control macro instruction are introduced and explained in the followinq 
paraqraphs. 
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Acquire a Journal Control Area (TYPE=GETJCA) 

The format of the DFHJC macro instruction to acquire a journal control 
area (JCA) is as follows: 



III I 

| | DFHJC | TYPE=GETJCA | 

III I 

i i i i 

This macro specifies that an area to be used for communication 
between the application program and the CICS/VS journal control program 
is to be acquired. The address of the JCA is returned in TCAJCAAD to 
the application program. 

If journal output services are requested in an application program 
through DFHJC macro instructions, the application programmer must 
provide the symbolic definition of the JCA by copying the CICS/VS 
storage area map DFHJCADS. The JCA must be acquired for the task prior 
to any journal output requests by issuing the macro instruction: 

DFHJC TYPE=GETJCA 

The JCA may be acquired separately, as shown above, in which case no 
other operands are needed. Alternatively, the JCA may be acquired by 
and with the program's first journal output request; for example: 

DFHJC TY.PE= (GETJCA,PUT) 

If the latter approach is chosen, then it is not possible to place 
additional parameter values for the output request directly into the JCA 
prior to the request, because the JCA does not exist prior to this 
request. If any such request is attempted, warning messages are issued 
and the reguest is not processed. 

In addition to acquiring the JCA for the task, the DFHJC TYPE=GETJCA 
macro instruction establishes addressability to the area by moving the 
contents of the JCA address field (TCAJCAAD) to JCABAR, the base locator 
specified for the area. Once acquired for the task, the JCA is reused 
for all subsequent journal requests issued by or on behalf of the task. 
Subsequent TYPE=GBTJCA requests only cause JCABAR to be reloaded with 
the same value. The JCA may not be released by the user. 

The following examples show how to acquire the journal control area 
(JCA) for the task: 

For Assembler language : 

COPY DFHTCADS COPY TCA SYMBOLIC DEFINITIONS 



JCABAR EQU 10 ASSIGN BASE REGISTER FOR JCA 

COPY DFHJCADS COPY JCA SYMBOLIC DEFINITIONS 



GETJCA DFHJC TYPE=GETJCA REQUEST ACQUISITION OF THE JCA 
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F or COBOL : 

02 JCABAR PIC S9 (8) COMP 



NOTE DEFINE BASE LOCATOR FOR JCA. 



01 DFHTCADS COPY DFHTCADS. 



NOTE COPY TCA SYMBOLIC DEFINITIONS 



01 DFHJCADS COPY DFHJCADS. 



NOTE COPY JCA SYMBOLIC DEFINITIONS 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR 



NOTE LOAD TCA BASE LOCATOR VALUE. 



GETJCA. 

DFHJC TYPE=GETJCA 



REQUEST ACQUISITION OF THE JCA 



For PL/I : 
^INCLUDE DFHTCADS; 



/♦COPY TCA SYMBOLIC DEFINITIONS*/ 



^INCLUDE DFHJCADS; 



/♦COPY JCA SYMBOLIC DEFINITIONS*/ 



GETJCA: 

DFHJC TYPE=GETJCA 



REQUEST ACQUISITION OF THE JCA 
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Create a Journal Record and Wait for Output (TYPE=PUT) 

The format of tha DFHJC macro instruction to create a journal record, 
initiate its output, and wait for completion is as follows: 




TYPE=£PUT| (WRITE, WAIT)} 
, JFILEID= {nn | SYSTEM | YES} 
, JTYPEID= {nnnn | YES} 
,JCDADDR= {symbolic address|YES} 
,JCDLGTH= {decimal value | YES} 
,PFXADDR= {symbolic address| YES} ] 
,PFXLGTH= {decimal value | YES} ] 
,STARTIO={YES|NO} ] 
,NORESP=symbolic address) 
,IDERROR=symbolic address] 
,LERROR=symbolic address] 
,IOERROR=symbolic address] 
,NOTOPEN=symbolic address] 
,INVREQ=symbolic address] 
,STATERR=symbolic address] 



This macro specifies that a journal record is to be created in the 
journal buffer area and then written out; the requesting task will wait 
until the physical record has been written. TYPE= (WRITE, WAIT) implies, 
and is equivalent to, TYPE=POT. 

Because the maximum buffer length that can be used to write a journal 
record is 32,767 bytes, the combined length specified by JCDLGTH and 
PFXLGTH (or stored in JCALDATA and JCALPRFX, respectively) cannot exceed 
32,767. 

The STARTIO=YES operand specifies that the journal record is to be 
written out immediately. This is also the default. If STARTIO=NO is 
specified, initiation of output will be delayed until either the journal 
buffer is full, output is initiated by another request to the same 
journal, or one second elapses. 

Use of this macro ensures that the journal record is written on the 
auxiliary storage device associated with the journal before processing 
continues; the task is said to be "synchronized 1 with the output event. 
Most CICS/VS— provided data output service is performed in a synchronous 
manner. 

The application programmer may request synchronous journal output 
services either by a DFHJC TYPE=PUT macro instruction as above, or by 
specifying DFHJC TYPE= (WRITE, WAIT) . In both cases, certain additional 
keyword operands are mandatory. These keywords are JFILEID (the journal 
data set to receive data), JCDADDR (the address of the *iser data to be 
included in the journal record) , JCDLGTH (the length of the user data) , 
and JTYPEID (the two-byte user— specified hexadecimal identifier for the 
journal record) . Optional accompanying keywords are PFXADDR (the 
address of user prefix data for inclusion in the journal record) and 
PFXLGTH (the length of the user prefix data); the application programmer 
may also include keyword operands to direct control to exception- 
handling routines in the program. (See "Test Response to a Request for 
Journal Services," later in this chapter.) 

The following examples show how to request and wait for journal 
output service. 
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For A ssembler lan gu a ge : 
COPY DFHTCADS 



COPY TCA SYMBOLIC DEFINITIONS 



JCABAR 


EQU 


10 




COPY 


DFHJCADS 


FWACBAR 


EQU 


9 




COPY 


DFHFWADS 


RECORD 


DS 


0CL90 


KEYDATA 


DS 


0CL8 


ACCNTNO 


DS 


PL4 


AMOUNT 


DS 


PL4 


NAME 


DS 


CL20 


ADDRESS 


DS 


CL40 



ASSIGN BASE RBGISTE2 FOR JCA 
COPY JCA SYMBOLIC DEFINITIONS 



ASSIGN BASE REGISTER FOR FWA 
COPY FWA SYMBOLIC DEFINITIONS 



DFHJC TYPE=PUT, 
JFILEID=2 , 
JCDADDR=KEYDATA, 
JCDLGTH=8, 
JTYPEID=0F01, 
NORESP=OK 



REQUEST SYNCHRONOUS OUTPUT * 

TO JOURNAL ID 2, * 

OF THE •KEY* DATA, * 

OF LENGTH=8 BYTES. * 

(IDENTIFIER FOR JOURNAL RECORD) * 
BRANCH ADDR FOR NORMAL RESPONSE 



OK 



DS 



OH 
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F or COBOL ; 

02 JCABAR PIC S9 (8) COMP. 



MOTE DEFINE BASE LOCATOR FOR JCA 



01 DFHTCADS COPY DFHTCADS. 



NOTE COPY TCA SYMBOLIC DEFINITIONS 



01 DFHJCADS COPY DFHJCADS. 



NOTE COPY JCA SYMBOLIC DEFINITIONS 



01 DFHFWADS COPY DFHFHADS. 
02 RECORD. 

03 KEYDATA. 

04 ACCNTNO PIC S9 (7) COMP-3. 
04 AMOUNT PIC S9(7) COMP-3. 
03 NAME PIC X (20) . 
03 ADDRESS PIC X (40) . 



NOTE COPY FHA SYMBOLIC DEFINITIONS 



PROCEDURE DIVISION. 

HOVE CSACDTA TO TCACBAR. 



NOTE LOAD TCA BASE LOCATOR VALUE, 



DFHJC TYPE=PUT, 
JFILEID=2, 
JCDADDR=KEYDATA, 
JCDLGTH=8, 
JTYPEID=0F01, 
NORESP=OK 



REQUEST SYNCHRONOUS OUTPUT 
TO JOURNAL ID 2, 
OF THE 'KEY 1 DATA, 
OF LENGTH=8 BYTES. 
(IDENTIFIER FOR JOURNAL RECORD) 
BRANCH ADDR FOR NORMAL RESPONSE 



OK. 
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For PL/I: 

^INCLUDE DFHTCADS; /*COPY TCA SYMBOLIC DEFINITIONS*/ 

%INCLUDE DFHJCADS; /*COPY JCA SYMBOLIC DEFINITIONS*/ 



36INCLUDE DFHFHADS; /*COPY FWA SYMBOLIC DEFINITIONS*/ 

02 RECORD, 

03 KEYDATA, /*8-BYTE MINOR STRUCTURE*/ 

04 ACCNTNO FIXED DECIMAL (7), 
04 AMOUNT FIXED DECIMAL (7) , 
03 NAME CHAR (20) , 
03 ADDRESS CHAR (40) , 



DFHJC TYPE=PUT, REQUEST SYNCHRONOUS OUTPUT * 

JFILEID=2, TO JOURNAL ID 2, * 

JCDADDR=KEYDATA, OF THE »KEY» DATA, * 

JCDLGTH=8, OF LENGTH=8 BYTES. * 

JTYPEID=0F01, (IDENTIFIER FOR JOURNAL RECORD) * 

NORESP=OK BRANCH ADDR FOR NORMAL RESPONSE 



OK 
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Create a Journal Record (TYPE = WRITE) 



Tha general format of the DFHJC macro instruction to create a journal 
record for subsequent output is as follows: 




TYPE=WRITE 

,JFILEID={nn| SYSTEM | YES} 

, JTYPEID= {nnnn | YES} 

,JCDADDR= {symbolic address| YES} 

,JCDLGTH= {decimal value | YES} 
[ ,PFXADDR= {symbolic address| YES} ] 
[ ,PFXLGTH= {decimal value | YES}] 
[ ,STARTIO={YES|NO} ] 
[ ,COND={ (YES, symbolic address) | NO} ] 
[ ,NORESP=symbolic address] 
[ r IDERROR=symbolic address] 
[ ,LERROR=symbolic address] 
[ ,NOTOPEN=symbolic address] 
[ ,INVREQ=symbolic address] 
[ , STATERR=syrabolic address] 



This macro causes a journal record to be created in the journal 
buffer area, but allows the requesting task to retain control and thus 
to continue with other processing. 

At some later time, the task may wish to ensure that the journal 
record has been written. If the JCA is to be used for any other journal 
requests, that task should save the event control number (four bytes) 
returned in JCAECN after a journal record is successfully created in 
response to the DFHJC TYPE=WRITE request. The event control number must 
be restored to the JCA immediately before the DFHJC TYPE=WAIT request 
used to check and wait for output. If the JCA is not used in the 
interim for any other journal requests for the task, there is no need to 
save and restore the event control number. 

However, restoring the event control number prior to issuing a DFHJC 
TYPE=WAIT macro is a good programming practice. CICS/VS management 
modules also use the JCA of the task for journal requests. For example, 
automatic journaling is used in the file control program, and logging 
can be performed for recovery purposes at the user's option. 

Additional keyword operands applicable to TXPE=WRITE requests are as 
described above under "Create a Journal Record and Wait for Output." 

The basic process of building journal records in the buffer space of 
a given journal continues until such time as one of the following 
situations occurs: 

• A request is made for synchronous output of a journal record. 

• A request is rejected because of insufficient journal buffer space., 

• The available buffer space is reduced below a user— specif ied level 

(see the CICS/VS System Programmer's Reference Manual ) . 

At that time, all journal records present in the buffer, including 
any 'deferred 1 output resulting from asynchronous reguests, are written 
to external storage, as one block. 
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If a task creates deferred output and delays synchronizing, the 
deferred output may be written »for free 1 along with other requests; 
when the task attempts to synchronize, there will be no need for it to 
wait. Thus, the advantages that may be gained by deferring journal 
output are: (1) transactions may get better response times by waiting 
less, (2) the load of physical I/O reguests on the host system may be 
reduced, and (3) journal data sets may contain fewer but larger blocks 
and so better utilize external storage devices. 

However, these advantages are achievable only at the cost of more 
buffer space and greater programming complexity. It is necessary to 
plan and program to control synchronizing with journal output. 
Additional decisions which depend on the data content of the journal 
record and how it is to be used must be made in the application program. 
In any case, the full benefit of deferring journal output is obtained 
only when the load on the journal data set is high. 

The STARTIO keyword governs whether output is to be initiated (YES) 
or not (NO) . The default option is NO for WRITE requests and YES for 
PUT, (WRITE, WAIT) , or WAIT requests. The option NO should be used 
whenever possible because, if every journal request uses STARTIO=YES, no 
improvement over synchronous output requests, in terms of reducing the 
number of physical I/O operations and increasing the average block size, 
is possible. 

The COND keyword governs what happens if the journal buffer space 
available at the time is not sufficient to contain the journal record 
for the request. If the default option COND=NO is taken, the requesting 
task loses control. The contents of the current buffer are written out, 
and the journal record for this request is built in the resulting freed 
buffer space before control returns to the requesting task. 

If the requesting task is not willing to lose control, for example, 
if some housekeeping must be performed before other tasks get control, 
than COND= (YES, symbolic address) should be specified. If buffer space 
is momentarily insufficient, no journal record is built for the request, 
and control is returned directly to the requesting program at the 
location identified by symbolic address. The requesting program can 
perform any housekeeping needed before reissuing the journal output 
request. 

The following example shows how to request deferred journal output, 
but ensure that the requesting task retains control to perform 
housekeeping, if necessary. 



F or Assembler language : 



COMDATA 



COPY 
DS 



DFHCS&DS 
CL10 



COPY CSA SYMBOLIC DEFINITIONS 
AND COMMON WORK AREA 



COPY 
SAVEDATA DS 
MYDATA DS 



DFflTCADS 

CL10 

CL10 



COPY TCA SYMBOLIC DEFINITIONS 
SAVE AREA FOR COMMON DATA 
AREA FOR MY DATA 



JCABAR EQU 10 

COPY DFHJCADS 



ASSIGN BASE REGISTER FOR JCA 
COPY JCA SYMBOLIC DEFINITIONS 



MVC SAVEDATA, COMDATA 



SAVE COMMON DATA 
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MVC COMDATA,MYDATA 



REPLACE WITH MY DATA FOR WORKING 



DFHJC TYPE=WRITE, 

JCDADDR=COMDATA / 

JCDLGTH=10, 

JFILEID=SYSTEM, 

JTYPEID=0101, 

START10=NO, 

COND= (YES, RETRY) , 

NORESP=OK 



REQUEST ASYNCHRONOUS OUTPUT * 

OF COMMON DATA AREA, * 

LENGTH=10 BYTES, * 

TO SYSTEM LOG. * 

(IDENTIFIER FOR JOURNAL RECORD) * 

REQUEST DEFERRED OUTPUT, * 
BUT RETAIN CONTROL IF BUFFER FULL. * 
BRANCH ADDR FOR GOOD RESPONSE 



OK 



DS 



OH 



RETRY DS OH 

MVC MYDATA,COMDATA 
MVC COMDATA,SAVEDATA 
DFHJC TYPE=WRITE, 

JCDADDR=MYDATA, 

JCDLGTH=10, 

JFILEID=SYSTEM, 

JTYPEID=0101, 

COND=NO, 

STARTIO=NO, 

NORESP=OK 



HOUSEKEEPING: 
MOVE DATA, THEN 
RESTORE COMMON DATA. 

REQUEST ASYNCHRONOUS OUTPUT * 

OF DATA, * 

LENGTH=10 BYTES, * 

TO SYSTEM LOG. * 

(IDENTIFIER FOR JOURNAL RECORD) * 
IF BUFFER FULL, WE'LL WAIT. * 

DEFER OUTPUT. * 

BRANCH ADDR FOR GOOD RESPONSE 
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Fo r COBOL : 

02 JCABAR PIC S9 (8) COMP. 



NOTE DEFINE BASE LOCATOR FOE JCA. 



01 DFHCSADS COPY DFHCSADS 
02 COMDATA PIC X (10) . 



NOTE COPY CSA SYMBOLIC DEFINITIONS 
NOTE DEFINE COMMON DATA AREA. 



01 DFHTCADS COPY DFHTCADS, 
02 SAVEDATA PIC X (10) . 
02 MYDATA PIC X (10). 



NOTE COPY TCA SYMBOLIC DEFINITIONS 
NOTE SAVE AREA FOR COMMON DATA. 
NOTE AREA FOR MY DATA. 



01 DFHJCADS COPY DFHJCADS 



NOTE COPY JCA SYMBOLIC DEFINITIONS 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR. 



NOTE LOAD TCA BASE LOCATOR VALUE. 



MOVE COMDATA TO SAVEDATA 
MOVE MYDATA TO COMDATA. 



NOTE SAVE COMMON DATA. 

NOTE REPLACE WITH MY DATA FOR WORKING. 



DFHJC TYPE=WRITE, 

JCDADDR=COMDATA, 

JCDLGTH=10, 

JFILEID=SYSTEM, 

JTYPEID=0101 f 

STARTIO=NO, 

COND= (YES, RETRY) , 

NORESP=OK 



REQUEST ASYNCHRONOUS OUTPUT 
OF COMMON DATA AREA, 
LENGTH=10 BYTES, 
TO SYSTEM LOG. 

(IDENTIFIER FOR JOURNAL RECORD) 
REQUEST DEFERRED OUTPUT, 
BUT RETAIN CONTROL IF BUFFER FULL. 
BRANCH ADDR FOR GOOD RESPONSE 



OK. 



RETRY. 

MOVE COMDATA TO MYDATA. 

MOVE SAVEDATA TO COMDATA 
DFHJC TYPE=WEITE, 

JCDADDE=MYDATA, 

JCDLGTH=10, 

JFILEID=SYSTEM, 

JTYPEID=0101, 

STARTIO=NO, 

COND=NO, 

NORESP=OK 



NOTE DO HOUSEKEEPING, THEN RETRY. 
NOTE MOVE DATA, THEN. 
NOTE RESTORE COMMON DATA. 
REQUEST ASYNCHRONOUS OUTPUT 
OF MY DATA, 
LENGTH=10 BYTES, 
TO SYSTEM LOG. 

(IDENTIFIER FOR JOURNAL RECORD) 
REQUEST DEFERRED OUTPUT, 
BUT IF BUFFER FULL, WE CAN WAIT. 
BRANCH ADDR FOR GOOD RESPONSE 
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For PL/I : 

%INCLUDE DFHCSADS; 

DCL 01 DFHCSAWK BASED (CSACBAR) 
02 FILL CHAR (512 ), 
02 COMDATA CHAR (10) ; 



/♦COPY CSA SYMBOLIC DEFINITIONS*/ 
/♦AND COMMON WORK AREA*/ 



%INCLUDE DFHTCADS; 

02 SAVEDATA CHAR (10) , 
02 MYDATA CHAR (10), 



/♦COPY TCA SYMBOLIC DEFINITIONS*/ 
/♦SAVE AREA FOR COMMON DATA*/ 
/♦AREA FOR MY DATA+/ 



^INCLUDE DFHJCADS; 



/♦COPY JCA SYMBOLIC DEFINITIONS^/ 



SAVEDATA=COMDATA; 
COMDATA=MYDATA; 



/♦SAVE COMMON DATAV 

/♦REPLACE WITH MY DATA FOR WORKING*/ 



DFHJC TYPE=WRITE, 

JCDADDR=COMDATA, 

JCDLGTH=10 / 

JFILEID=SYSTEM, 

JTYPEID=0101, 

STARTIO=NO, 

COND=(YES, RETRY) , 

NORESP=OK 



REQUEST ASYNCHRONOUS OUTPUT * 

OF COMMON DATA AREA, * 

LENGTH=10 BYTES, * 

TO SYSTEM LOG. * 

(IDENTIFIER FOR JOURNAL RECORD) * 

REQUEST DEFERRED OUTPUT, * 
BUT RETAIN CONTROL IF BUFFER FULL. * 
BRANCH ADDR FOR GOOD RESPONSE 



OK: 



RETRY: 

MYDATA=COMDATA; 

COMDATA=SAVEDATA; 

DFHJC TYPE=WRITE, 

JCDADDR=MYDATA, 

JCDLGTH=10, 

JFILEID=SYSTEM, 

JTYPEID=0101, 

STARTIO=NO, 

COND=NO, 

NORESP=OK 



/♦HOUSEKEEPING :♦/ 
/♦MOVE DATA, THENV 
/♦RESTORE COMMON DATA.V 
REQUEST ASYNCHRONOUS OUTPUT 
OF MY DATA, 
LENGTH=10 BYTES, 
TO SYSTEM LOG. 

(IDENTIFIER FOR JOURNAL RECORD) 
REQUEST DEFERRED OUTPUT, 
BUT IF BUFFER FULL, WE CAN WAIT. 
BRANCH ADDR FOR GOOD RESPONSE 
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Wait for Output of a Journal Record (TYPE=WAIT) 

The general format of the DFHJC macro instruction to wait for output of 
a previously created journal record is as follows: 




TYPE=WAIT 

, JFILEID= {nn | SYSTEM | YES} 
[ ,STARTIO={YES|NO} ] 
[ / NOBESP=symbolic address] 
[ ,IDERROR=symbolic address ] 
[ ,IOERROR=symbolic address] 
[ ,NOTOPEN=symbolic address] 
[ ,INVREQ=symbolic address] 



This macro specifies that the requesting task is to be placed in a 
wait state until the block containing a journal record has been written 
as output (that is, the journal operation is to be synchronized with 
continued execution of the task issuing the journal write request) . If 
the block containing the journal record has not been written, the 
requesting task is placed in a wait state until the write is completed. 
The operand can be specified if the user has restored the event control 
number, because JCAJFID is part of the event control number. 

Before issuing a synchronizing reguest, the task must ensure that the 
event control number (four bytes) corresponding to the journal record in 
question is in field JCAECN of the JCA. An event control number is 
returned in JCAECN after every successful journal output reguest. Since 
the JCA is used for every journal request issued by the task (or by 
CICS/VS on its behalf) , the requesting program must save the event 
control number immediately after an asynchronous output reguest if it is 
to be used later. This is necessary because the particular event 
control number may be overwritten during reuse of the JCA. 

If the JCA is not reused between the output request and the 
synchronize request, the reguesting program need not save and restore 
the event control number. It is the user *s responsibility to determine 
whether or not he needs to save and restore it. 

If the reguesting program has made a succession of successful 
asynchronous output requests to the same journal data set, it is only 
necessary to synchronize on the last of these requests to ensure that 
all of the journal records have reached the external storage device. 
This may be done either by issuing a stand-alone DFHJC TYPE=WAIT 
request, or by making the last output request itself synchronous, a 
DFHJC TYPE=PUT or TYPE= (WRITE, WAIT) . 

The following examples show a typical sequence of instructions to 
request synchronization with the output of a journal record. 



For Assembler language ; 



COPY 
SAVEDECN DS 
JDATA DS 



DFHTCADS 

CL4 

CL36 



COPY TCA SYMBOLIC DEFINITIONS 
SAVED EVENT CONTROL NUMBER 
DATA TO WRITE TO JOURNAL 



JCABAR EQU 10 



ASSIGN BASE REGISTER FOR JCA 
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COPY DPHJCADS 



COPY JCA SYMBOLIC DEFINITIONS 



DFHJC TYPE=WRITE, 

JCDADDR=JDATA, 



N0EESP=0K1 



REQUEST ASYNCHRONOUS OUTPUT 

OP DATA AT JDATA, 

ETC. 



BRANCH TO OK1 IF GOOD RESPONSE 



OK1 DS OH 

MVC SAVEDECN, JCAECN 



SAVE EVENT CONTROL NUMBER 



MVC JCAECN, SAVEDECN 
DFHJC TYPE=WAIT, 
NORESP=OK2 



OK2 DS OH 



For COBOL 



02 JCABAR PIC S9 (8) COMP 



RESTORE EVENT CONTROL NUMBER, 
AND SYNCHRONIZE WITH OUTPUT. 
BRANCH TO OK2 IF GOOD RESPONSE 



NOTE DEFINE BASE LOCATOR FOR JCA. 



01 DFHTCADS COPY DFHTCADS, 
02 SAVEDECN PIC X (4) . 
02 JDATA PIC X(36) . 



NOTE COPY TCA SYMBOLIC DEFINITIONS 
NOTE SAVED EVENT CONTROL NUMBER. 
NOTE DATA TO WRITE TO JOURNAL. 



01 DFHJCADS COPY DFHJCftDS, 



NOTE COPY JCA SYMBOLIC DEFINITIONS 



PROCEDURE DIVISION. 

MOVE CSACDTA TO TCACBAR. 



NOTE LOAD TCA BASE LOCATOR VALUE. 



DFHJC TYPE=WRITE, 

JCDADDR=JDATA, 



N0RESP=0K1 



REQUEST ASYNCHRONOUS OUTPUT 

OF DATA AT JDATA, 

ETC. 



BRANCH TO OK1 IF GOOD RESPONSE 



OK1. 

MOVE JCAECN TO SAVEDECN 



NOTE SAVE EVENT CONTROL NUMBER. 



MOVE SAVEDECN TO JCAECN. 



NOTE RESTORE EVENT CONTROL NUMBER. 
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DPHJC TYPB=WflIT, 
N0RESP=0K2 



AND SYNCHRONIZE WITH OUTPUT . 
BRANCH TO OK2 IF GOOD RESPONSE. 



OK2. 



For PL/I ; 

^INCLUDE DFHTCADS; 

02 SAVEDECN CHAR (4), 
02 JDATA CHAR (36); 



/*COPY TCA SYMBOLIC DEFINITIONS*/ 
/*SAVED EVENT CONTROL NUMBER*/ 
/*DATA TO WRITE TO JOURNAL*/ 



%INCLUDE DFHJCADS; 



/*COPY JCA SYMBOLIC DEFINITIONS*/ 



DFHJC TYPE=WRITE, 

JCDADDR=JDATA, 



NORESP=OK1 



REQUEST ASYNCHRONOUS OUTPUT 

OF DATA AT JDATA, 

ETC. 



BRANCH TO OK1 IF GOOD RESPONSE 



OK1: 
SAVEDECN=JCAECN; 



/*SAVE EVENT CONTROL NUMBER*/ 



JCAECN=SAVEDECN; 

DFHJC TYPE=WAIT, 
NORESP=OK2 



/♦RESTORE EVENT CONTROL NUMBER,*/ 
AND SYNCHRONIZE WITH OUTPUT. * 
BRANCH TO OK2 IF GOOD RESPONSE 



OK2: 
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Test Response to a Request for Journal Services (TYPE = CHECK) 

The general format of the DFHJC macro instruction to check the CICS/VS 
response to a request for journal services is as follows: 




TYPE=CHECK 

[ , NORESP=symbolic address] 
[ ,IDERROE=symDolic address] 
[ ,LERROR=symbolic address] 
[ , IOERROR=symbolic address] 
[ ,NOTOPEN=symbolic address] 
[ ,INVRBQ=symJ>olic address] 
[ ,STATERR=symbolic address] 



I Journal Control Response Codes 



| To test a response code the application programmer must know the actual 
settings of the response code, which is returned at JCAJCRC. The 
possible response codes and the requests, conditions, and keyword 
operands to which they correspond are identified in Figure 7.5—1. 
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1 

I Journal Reguest 
I by DFHJC Macro 
| Instruction 


Condition 


Response 


i 

> codes in JCAJCRC | 


Assembler | 


COBOL 


PL/I | 


| PUT, WRITE, WAIT, 
| CHECK 


NORESP 
(Normal response) 


X»00» | 


LOW-VALUES 
(JCARCNR) 


ooooooooi 


| PUT, WRITE, WAIT, 
| CHECK 


IDERROR 
(Journal identi- 
fication error) 


X»01» | 


12-1-9 
(JCARCIDE) 


000000011 


| PUT, WRITE, CHECK 


LERROR 
(Journal record 
length error) 


X»06« 


12-6-9 
(JCARCLE) 


000001101 


| PUT, WAIT, CHECK 


IOERROR 
(Output I/O error) 


X»07» 


1 2-7-9 
(JCARCIOE) 


000001111 


| PUT, WRITE, WAIT, 
| CHECK 


NOTOPEN 
(Journal not open) 


X'05» 


12-5-9 

(JCARCNOE) 


000001011 


I PUT, WRITE, WAIT, 
| CHECK 


INVREQ 
(Invalid reguest) 


X , 02» 


1 2-2-9 
(JCARCIRE) 


000000101 


| PUT, WRITE, CHECK 


STATERR 
(Reguest incompat- 
ible with current 
status of journal 


X»03» 


12-3-9 
I (JCARCSE) 


! 00000011| 


1 Note: 1 
I The names enclosed in parentheses in the COBOL column indicate | 
| the condition names generated by CICS/VS. These names may be | 
| used in testing for the conditions in a COBOL program. | 

i . _ , _. _. .,, ._,,,. ,. _. . , . ... .,- ,_ _ _ „_ ._i 



Figure 7.5—1. Journal Control Response Codes 

If the application programmer does not provide for checking a 
particular response code and the corresponding condition occurs, program 
execution resumes at the instruction immediately following the DFHJC 
macro instruction which reguested the journal service. 
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Operands of DFHJC Macro 



COND = 

specifies that control is to be returned to the application 
program if the request cannot be satisfied immediately because 
insufficient journal buffer space is available. If control is 
to be returned, the point of return must be specified as a 
second parameter of this operand . 

(YES, symbolic address) 

indicates that control is to be returned to the location 
represented by symbolic address in the application program 
if the request cannot be satisfied immediately. No journal 
record will have been created for the request. 

NO 

indicates that the contents of the current buffer are to be 
written out and the requesting task placed in a wait state 
until its request has been satisfied (by the building of a 
record in buffer space freed by the write operation). 

IDERROR=symbolic address 

is the address to which control is to be returned if the 
specified journal file identification does not exist in the 
journal control table (JCT) . 

INVREQ=symbolic address 

is the address to which control is to be returned if the TYPE 
operand is invalid. 

IOERROR=symbolic address 

is the address to which control is to be returned if the 
physical output of a journal record was not accomplished 
because of an unrecoverable I/O error. This operand is 
applicable only to requests that may cause a wait for 
completion of output, that is, to TYPE=PUT, TYPE= (WRITE , WAIT) , 
or TYPE=WAIT. 



JCDADDR 



is the address of the user data to be built into the journal 
record. 

symbolic address 

is the symbolic address of the user data. 



YES 



indicates that the address of the user data has been placed 
in JCAADATA prior to issuing this macro instruction. 



JCDLGTH= 



is the length of the user data to be built into the journal 
record. 

decimal value 

is a decimal numeral in the range from 1 to 32000 (or a 
lower maximum, because of the journal buffer size) , 
indicating the length, in bytes, of the user data. 
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YES 

indicates that the length, in binary, of the user data has 
been placed in JCALDATA prior to issuing this macro 
instruction. 

JFILEID= 

is the one— byte identification of the journal file (data set) 
referred to in this journal operation. 

nn 

is a decimal value in the range from 2 through 99 to be 
taken as the journal file identification. 

SYSTEM 

indicates that the system log data set is the journal for 
this operation. 

YES 

indicates that the journal file identification has been 
placed in JCAJFID prior to issuing this macro instruction. 

JTYPEID= 

is an identifier to be placed in the journal record to identify 
its origin. 

nnnn 

is a one— to four— character hexadecimal value to be taken 
as the identifier for the journal record; if fewer than 
four characters are specified, padding with zeros occurs on 
the right. 



YES 



indicates that the journal record identification has been 
placed in JCAJRTID prior to issuing this macro instruction. 



LERROR=symbolic address 

is the address to which control is to be returned if the 
computed length for the journal record exceeds the total buffer 
space allocated for the journal data set, as specified in the 
JCT entry for the data set. 

NORESP=symbolic address 

is the address to which control is to be returned if the 
requested operation was performed successfully. 

NOTOPEN=symbolic address 

is the address to which control is to be returned if the 
journal request cannot be satisfied because the specified 
journal data set has been disabled and is not available. 



PFXADDR= 



is the address of user prefix data to be included in the 
journal record. 

symbolic address 

is the symbolic address of the user prefix data. 
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YES 

indicates that the address of the user prefix data has been 
placed in JCAAPRFX prior to issuing this macro instruction. 

PFXLGTH= 

is the length of the user prefix data to be included in the 
journal record. 

decimal value 

is a decimal numeral in the range from 1 to 32000 (or a 
lower maximum, because of the Journal buffer size), 
indicating the length, in bytes, of the user prefix data. 

YES 

indicates that the length, in binary, of the user prefix 
data has been placed in JCALPRPX prior to issuing this 
macro instruction. 

STARTI0= 

specifies whether output of the journal record is to be 
initiated immediately. 

YES 

indicates that output of the journal record is to be 
initiated. 

indicates that no output operation is required at this 
time. 

The default value is YES if a synchronizing reguest is 
issued, namely POT, (WRITE, WAIT) , or WAIT. The default is 
NO for a simple WRITE request. If STARTIO=NO is specified 
with a synchronizing reguest the maximum delay allowed 
before output is initiated is one second. 

STATERR= 

is the address to which control is to be passed if the current 
status of the journal precludes the requested operation. For 
example, a status error will occur if a DFHJC TYPE=PUT macro is 
issued for a journal file that has been closed and then opened 
for input. This is because closing the file gave exclusive 
control to the requesting task but opening for input has not 
released exclusive control. (For further details, refer to the 
CICS/VS Sy stem Programm er's Guide. ) 



NO 
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Chapter 7.6. Recovery /Restart (SYNC Point) Control 
(DFHSP Macro) 



Sync point management works in conjunction with other CICS/VS 
components, such as transient data management and file management, to 
provide the user with facilities needed for an emergency restart after 
an abnormal termination of CICS/VS. In an emergency restart, changes 
made in protected resources (for example, in transient data 
intrapartition gueues) can be backed out for tasks that were "in flight" 
at the time of failure. This backout is based upon information about 
the tasks recorded on a system log during execution. 

Each synchronization point in an application program marks the 
completion of a logical unit of work . By definition, a logical unit of 
work (LUH) is an application programmer-defined unit of work that 
performs a complete processing function. One task may perform one LOW, 
or several LOHs, generally delimited by conversational terminal 
operations (a terminal write, followed by a terminal read). 



Specify a Synchronization Point (TYPE=USER) 

The format of the DFHSP macro that specifies completion of a logical 
unit of work, or sync point, is as follows: 



i 1 1 

I I I 

| DFHSP | TYPE=USER | 



A sync point is always reguested by CICS/VS at termination of a task, 
The completion of a logical unit of work indicates to CICS/VS that: 

• All updates or modifications performed by the task are logically 
complete, and should not be backed out if a system failure occurs. 

• Functions reguested prior to the synchronization point, but 
deferred until the end of the logical unit of work, are to be 
processed, even if a subseguent system failure occurs. An example 
of such an operation is a purge of a transient data intrapartition 
gueue, as reguested by the application program. 

• All resources protected automatically on behalf of the task up to 
this point are to be released. An example of such a resource may 
be a transient data intrapartition destination that is logically 
associated with the task or a resource previously engueued by the 
user . 

• All resources previously engueued by the user are degueued. 

The location of a sync point for a task on the system log data set, 
relative to other logged activity for that task, determines the extent 
to which CICS/VS (or user programs) may need to provide transaction 
backout. Generally, sync points are not needed for short— duration 
tasks. 
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Sync points are also used by CICS/VS to delimit the extent to which 
user data set modifications may need to be backed out for a task. 
During emergency restart, CICS/VS collects all user data set 
modifications for tasks that were engaged in a LUW at the time of 
uncontrolled shutdown and copies them in a restart data set. The 
modifications can then be read by the CICS/VS transaction backout 
program or by user— written programs executed during the post- 
initialization phase of restart. 

Through these facilities, sync point management not only permits 
emergency restart but also provides the means by which the activity 
required for such restart can be controlled by the user. The functions 
performed by other CICS/VS programs involved in sync point/uncontrolled 
shutdown/emergency restart activities are explained in greater detail in 
the CICS/VS System Programmer's Referenc e Manual and CICS/VS 
S ystem/Application Design Guide . 

A sync point request for a task that is scheduled to use a DL/I 
resource implies the release of that resource. This means that if, 
after issuing a DFHSP TYPE=USER macro instruction, access to a DL/I data 
base is required, the desired PSB must be rescheduled through the DFHPC 
TYPE=(DL/I,PSB) macro instruction. The previous position of that data 
base has been lost. Conversely, when a DL/I termination instruction is 
issued, CICS/VS will issue a DFHSP TYPE=USER instruction on behalf of 
the task that is releasing a PSB. 

Any BMS logical message that has been started but not completed when 
a DFHSP macro is issued is forced to completion by means of an implied 
DFHBMS TYPE=PAGEOUT instruction. 

Note : If sync points are to be issued in a transaction that is eligible 
for transaction restart, the application programmer must seek advice 
from the systems programmer. 



I Backout Recoverable Resources (TYPE = ROLLBACK) (Assembler Language Only) 



The format of the DFHSP macro that restores recoverable resources is as 
follows: 



i 1 

I I 

| DFHSP | TYPE=ROLLBACK 



I I I 

I 1 L. 



This macro causes all changes to recoverable resources made by the 
task since its last sync point to be backed out so that those resources 
are then in the state that they were at the time the sync point was 
taken. 

After the recoverable resources have been restored, a sync point is 
taken and control is passed to the user. 
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Appendix A. Example of a CICS/VS Application Program 



This appendix contains an executable application program that performs a 
limited message switching function; that is, data collection, message 
entry, and message retrieval. The program is shown in each of the 
languages supported under CICS/VS: Assembler language, COBOL, and PL/I. 

********* ********* ****************************************** *********** 

* ASSEMBLER EXAMPLE PROBLEM * 
*********************************************************************** 

* TITLE »CICS/VS MESSAGE SWITCHING PROGRAM EXAMPLE* * 

DFHCOVER 
************************************************************ *********** 

**** APPLICATION PROGRAM **** 

*********************************************************************** 

*** DUMMY SECTIONS *** 

*********************************************************************** 

COPY COMMON SYSTEM AREA DSECT 
LISTING CONTROL CARD - EJECT 
COPY TASK CONTROL AREA DSECT 
TEMPORARY STORAGE RECORD LENGTH 

DESTINATION IDENTIFICATION 
RETRIEVE ALL INDICATOR 
QUEUE EMPTY MESSAGE CONTROL IND 
LISTING CONTROL CARD - EJECT 
TERM CONT TABLE TERM ENT ADR RG 
COPY TERM CONT TABLE TERM ENTRY 
TERM I/O AREA BASE ADDR REG 
COPY TERMINAL I/O AREA DSECT 
DATA AREA 

TRANSACTION IDENTIFICATION 
DELIMITER 

RESUME REQUEST IDENTIFICATION 
RETRIEVE ALL INDICATOR 1 
DESTINATION IDENTIFICATION 
SUSPEND STORAGE FACILITY IDENT 
DELIMITER 

TERMINAL MESSAGE BEGINNING ADDR 
RETRIEVE ALL INDICATOR 2 
*********************************************************************** 

SPACE 8 LISTING CONTROL CARD - SPACE 8 

TDIABAR EQU 9 TRANS DATA IN AREA BASE ADDR RG 

COPY DFHTDIA COPY TRANS DATA INPUT AREA 

EJECT LISTING CONTROL CARD - EJECT 





COPY 


DFHCSADS 




EJECT 






COPY 


DFHTCADS 


TWATSRL 


DS 


H 




DS 


H 


TWATDDI 


DS 


CL4 


TWAREAI 


DS 


CL4 


TWAQEMCI 


DS 

EJECT 


C 


TCTTEAR 


EQU 


11 




COPY 


DFHTCTTE 


TIOABAR 


EQU 


10 




COPY 


DFHTIOA 


TIOADATA 


DS 


0CL80 


T 10 AT ID 


DS 


CL4 




DS 


C 


TIOARRI 


DS 


0CL6 


TI0ARAI1 


DS 


0CL3 


TIOADID 


DS 


CLU 


TIOASSF 


DS 


0CL4 




DS 


C 


TIOAMBA 


DS 


OC 


TI0ARAI2 


DS 


CL3 
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MCPDIEM 


DC 




DC 




DC 




DC 




DC 




DC 


MCPDEML 


EQU 



* * *** * *** ***** **** ****** ****** 4c ** *** **** *********** ******************* * 

**** APPLICATION PROGRAM **** 

*********************************************************************** 

CICSATP CSECT CONTROL SECTION - APPL TEST PGM 

USING *,3 USING REGISTER 3 AT * 

LR 03,14 LOAD PROGRAM BASE REGISTER 

B ATPIPIN GO TO INIT PROG INSTR ENTRY 

*********************************************************************** 

EJECT LISTING CONTROL CARD - EJECT 

*********************************************************************** 

*** DECLARATIVES *** 

*********************************************************************** 

Y(MCPDEML-4) TERMINAL MESSAGE LENGTH 

H»0« 

X»15» NEW LINE SYMBOL CONSTANT 

08XM7* HARDCOPY TERM IDLE CHARACTERS 

C'DESTINATION IDENTIFICATION ERROR - PLEASE RESUBMIT' 

X»15» NEW LINE SYMBOL CONSTANT 

♦-MCPDIEM TERMINAL MESSAGE TOTAL LENGTH 

*********************************************************************** 
*********************************************************************** 

* DATA COLLECTION * 
*********************************************************************** 

Y (L'DCPDCAMD) DATA COLL ACKNOWLEDGMENT LEN 
H'O* 

C» DATA COLLECTION HAS BEEN REQUESTED AND IS ABOUT TO BE* 
GIN • DATA COLLECTION ACKNOWLEDGMENT 

Y (L'DCPEODMD) END OP DATA MESSAGE LENGTH 
H«0« 

C» THE DATA HAS BEEN RECEIVED AND DISPATCHED TO THE DESI* 
GNATED DESTINATION • END OF DATA MESSAGE 

Y (L'DCPEOVMD) 
H«0» 

C» END OF VOLUME REQUEST HAS BEEN RECEIVED » 
Y(DCPSRAL-4) TERMINAL MESSAGE LENGTB 

R»0« 

X«15» NEW LINE SYMBOL CONSTANT 

08XM7* HARD COPY TERM IDLE CHARACTERS 

CDATA COLLECTION SUSPENSION HAS BEEN REQUESTED* 
X»15« NEW LINE SYMBOL CONSTANT 

*-DCPSRAM TERMINAL MESSAGE TOTAL LENGTH 

Y(DCPRRAL-4) TERMINAL MESSAGE LENGTH 

H»0» 

X'15' NEW LINE SYMBOL CONSTANT 

08XM7* HARDCOPY TERM IDLE CHARACTERS 

C'DATA COLLECTION RESUMPTION HAS BEEN REQUESTED AND IS • 
C'ABOUT TO BEGIN' 
X'15 1 NEW LINE SYMBOL CONSTANT 

*-DCPRRAM TERMINAL MESSAGE TOTAL LENGTH 

*********************************************************************** 

SPACE 4 LISTING CONTROL CARD - SPACE 4 

*********************************************************************** 

* MESSAGE ENTRY * 
*********************************************************************** 

MEPMEAML DC Y (L» MEPMEAMD ) MSG ENTRY ACKNOWLEDGMENT LNGTH 

DC H » • 

MEPMEAMD DC C» YOUR MESSAGE HAS BEEN RECEIVED AND DISPATCHED TO THE * 

DESIGNATED DESTINATION • MESSAGE ENTRY ACKNOWLEDGMENT 
*********************************************************************** 

SP^CB 4 LISTING CONTROL CARD - SPACE 4 

*********************************************************************** 

* MESSAGERETRIEVAL * 
*********************************************************************** 

MRPNMMM DC Y(MRPNMML-4) TERMINAL MESSAGE LENGTH 

DC H»0" 
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DCPDCAML 


DC 




DC 


DCPDCAMD 


DC 


DCPEODML 


DC 




DC 


DCPEODMD 


DC 


DCPEOVML 


DC 




DC 


DCPEOVMD 


DC 


DCPSRAM 


DC 




DC 




DC 




DC 




DC 




DC 


DCPSRAL 


EQU 


DCPRRAM 


DC 




DC 




DC 




DC 




DC 




DC 




DC 


DCPRRAL 


EQU 



DC X»15' NEW LINE SYMBOL CONSTANT 

DC 08XM7* 4ARDCOPY TERM IDLE CHARACTERS 

DC C»THERE ARE NO HORE • 

DC CT^S SAGES QUSJ3D FOR THIS DESTINATION 1 

DC X'15' NEW LINE SYMBOL CONSTANT 

MRPNMML EQU *-MRPNMMM TERMINAL MESSAGE TOTAL LENGTH 

MRPNMQM DC Y(MRPNQML-4) TERMINAL MESSAGE LENGTH 

DC H 1 *)' 

DC X'15 1 NEW LINE SYMBOL CONSTANT 

DC 08X«17» HARDCOPY TERM IDLE CHARACTERS 

DC C'THERE ARE NO MESSAGES QUEUED FOR THIS DESTINATION 1 

DC X'15' NEW LINE SYMBOL CONSTANT 

MRPNQML EQU *-MRPNMQM TERMINAL MESSAGE TOTAL LENGTH 
*********************************************************************** 

EJECT LISTING CONTROL CARD - EJECT 

*********************************************************************** 

*** IMPERATIVES * * * 

*********************************************************************** 
* * * * 

*********************************************************************** 

DS OD STORAGE ALIGNMENT - DOUBLEWORD 

DC CL32 'MESSAGE CONTROL PROGRAM 1 
ATPIPIN DS OD 
L 
L 
CLC 



INITIAL PROGRAM INSTRUCTION ENT 

LOAD TERM CONT AREA ADDR REG 

LOAD TERM I/O AREA ADDR REG 

COMPARE TRANSACTION IDENT 

GO TO DATA COLLECTION PROG IF = 

COMPARE TRANSACTION IDENT 

GO TO MESSAGE ENTRY PROG IF = 

COMPARE TRANSACTION IDENT 

GO TO MESSAGE RETRIEVAL PROG 



TCTTEAR,TCAFCAAA 

TIOABAR,TCTTEDA 

=C«DSDC«,TIOATID 
BE ALPDCPN 
CLC =C«DSME» ,TIOATID 
BE ALPMEPN 
CLC =C«DSMR«,TIOATID 
BE ALPMRPN 
DFHPC TYPE= ABEND, * 

ABCODE=XAPT 
EJECT LISTING CONTROL CARD - EJECT 

*********************************************************************** 

** APPLICATION LOGIC ** 

*********************************************************************** 

** DATACOLLECTION * * 

****************** ****** ************^c*** ********************** ********* 

DC CL32»DATA COLLECTION PROGRAM 1 
*********************************************************************** 



ALPDCPN 



DS 

CLC 

BNE 

MVC 

MVC 

MVC 



OH DATA COLLECTION PROGRAM ENTRY 

=C RESUME 1 , TIOARRI COMPARE FOR RESUME REQUEST 

DCPRRBN GO TO RESUME REQUEST BYPASS 

TIOATDL (DCPRRAL) ,DCPRRAM MOVE TERMINAL MESSAGE TO OUTPUT 



MOVE TEMP STRG DATA IDENT 
MOVE TEMP STRG DATA IDENT 



FORCED END OF VOLUME ROUTINE 
ISSUE TRANSIENT DATA MACRO 



TCATSDI(4) ,=C»DSDC» 

TCATSDI+4 (4) ,TCTTETI 
DFHTS TYPE=GET, 

TSDADDR=TWATSRL, 

NORESP=DCPRRNR, 

RELEASE=YES 
DFHPC TYPE=ABEND, 

ABCODE=XDCR 
DCPFEOV EQU * 

DFHTD TYPE=FEOV 

MVC TIOATDL ( (4+L»DCPEOVMD) ) ,DCPEOVML 

DFHTC TYPE= (WRITE) 

B RETURN 
*********************************************************************** 

DCPRRBN EQU * RESUME REQUEST BYPASS ENTRY 

MVC TWATDDI,TIOADID MOVE DESTINATION IDENTIFICATION 

MVC TCATDDI,TWATDDI 

CLC TIOAMBA (4),=C»FEOV» CHECK FOR FORCED END OF VOL REQ 

BE DCPFEOV BRANCH TO END OF VOLUME ROUTINE 

MVC TIOATDL ( (U+L 'DCPDCAMD) ) ,DCPDCAML 
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DCPRRNR EQU * RESUME REQUEST NORMAL RESPONSE 

DFHTC TYPE = (WRITE) 
DFHTC TYPE=(READ) 

*********************************************************************** 



LISTING CONTROL CARD - SPACE 4 
TERMINAL EVENT WAIT ENTRY 

LOAD TERM I/O AREA ADDR REG 

GO TO DUMP TRANSACTION STORAGE 
COMP DATA FOR EOD INDICATION 
GO TO EXIT IF EQUAL 
COMPARE FOR SUSPEND REQUEST 
GO TO SUSPEND REQUEST BYPASS 
MOVE TEMP STRG RECORD LENGTH 
MOVE TEMP STRG DATA IDENT 
MOVE TEMP STRG DATA IDENT 

GO TO MAIN STRG FACILITY BYPASS 



SPACE 4 
DCPTEWN DS OH 

DFHTC TYPE=(WAIT) 

L TIOABAR,TCTTEDA 

CLC =C»DUMP , ,TIOATID 

BE DCPDPTS 

CLC =C , EOD»,TIOADBA 

BE DCPEXIT 

CLC =C , SUSPEND»,TIOADBA 

BNE DCPSRBN 

MVC TWATSRL,=H , 32» 

MVC TCATSDI (4) ,=C , DSDC« 

MVC TCATSDI+4 (4) ,TCTTETI 

CLC =C»MAIN»,TIOASSF 

BNE DCPSRMB 

DFHTS TYPE=PUT, 

TSDADDR=TWATSRL, 

STORFAC=MAIN 
B DCPSRAB 
EQU * 
DFHTS TYPE=PUT, 

TSDADDR=TWATSRL, 

STORFAC=AUXILIARY 
EQU * 
DFHTS TYPE=CHECK, 1 

NORESP=DCPSRNR 
DFHPC TYPE=ABEND, =< 

ABCODE=XDCS 
EQU * SUSPEND REQUEST NORMAL RESPONSE 

MVC TIOATDL (DCPSRAL) ,DCPSRAM MOVE TERMINAL MESSAGE TO OUTPUT 
DFHTC TYPE= (WRITE) 

GO TO RETURN ENTRY 

SUSPEND REQUEST BYPASS ENTRY 

MOVE DESTINATION IDENTIFICATION 



DCPSRMB 



DCPSRAB 



DCPSRNR 



DCPSRBN 



GO TO AUX STRG FACILITY BYPASS 
MAIN STORAGE FACILITY BYPASS 



AUX STORAGE FACILITY BYPASS 



B 

EQU 
MVC 
XC 



RETURN 

* 

TCATDDI,TWATDDI 

TCTTEDA,TCTTEDA 



RESET TERMINAL DATA ADDRESS 



LOAD TERMINAL DATA LENGTH 
INCREMENT TERMINAL DATA LENGTH 
STORE TERMINAL DATA LENGTH 



DFHTC TYPE=(READ) 
LH 14, TIOATDL 
LA 14,4(0,14) 
STH 14, TIOATDL 
DFHTD TYPE=PUT, 

TDADDR=TIOATDL, 

NORESP=DCPNRCN, 

IDERROR=DCPDIEN 
DFHPC TYPE=ABEND, 

ABCODE=XDCP 
******************************************* 

DCPNRCN DS OH NORMAL RESP CODE ENTRY ADDRESS 

ST TIOABAR,TCASCSA STORE TERM I/O AREA ADDRESS 

DFHSC TYPE=FREEMAIN 
B DCPTEWN GO TO TERM EVENT WAIT ENTRY 

*********************************************************************** 

SPACE 4 LISTING CONTROL CARD - SPACE 4 

*********************************************************************** 

DCPDPTS EQU * DUMP TRANSACTION STOR ROUTINE 

DFHDC TYPE=TRANSACTION,DMPCODE=TRAN 

XC TCTTEDA,TCTTEDA CLEAR TERMINAL DATA AREA ADDR 

DFHTC TYPE= (READ) 

B DCPNRCN RETURN TO MAINSTREAM LOGIC 

*********************************************************************** 

SPACE 4 
*********************************************************************** 
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DCPEXIT EQU * EXIT 

MVC TIOATDL ( (4+L • DCPEODMD ) ),DCPEODML 

DFHTC TYPE= (WRITE) 

B RETURN GO TO RETURN ENTRY 

*********************************************************************** 

EJECT LISTING CONTROL CARD - EJECT 

*********************************************************************** 

* MESSAGE ENTRY * 
*********************************************************************** 

DC CL32 'MESSAGE ENTRY PROGRAM' 

*********************************************************************** 

ALPMEPN DS OH MESSAGE ENTRY PROGRAM ENTRY 

MVC TCATDDI,TIOADID MOVE DESTINATION IDENTIFICATION 

MVC TIOATID,TCTTETI MOVE SOURCE IDENTIFICATION 

LH 14, TIOATDL LOAD TERMINAL DATA LENGTH 

LA 14,4(0,14) INCREMENT TERMINAL DATA LENGTH 

STH 14, TIOATDL STORE TERMINAL DATA LENGTH 

DFHTD TYPE=PUT, * 

TDADDR=TIOATDL, * 

NORESP=MEPNRCN, * 

IDERROR=MEPDIEN 
DFHPC TYPE=ABEND, * 

ABCODE=XMEP 
*********************************************************************** 

MEPNRCN DS OH NORMAL RESP CODE ENTRY ADDRESS 

MVC TIOATDL ( (4 + L» MEPMEAMD) ) ,HEPMEAML 

DFHTC TYPE= (WRITE) 

B RETURN GO TO RETURN ENTRY 

*********************************************************************** 

EJECT LISTING CONTROL CARD EJECT 

*********************************************************************** 

* MESSAGERETRIEVAL * 
*********************************************************************** 

DC CL32'MESSAGE RETRIEVAL PROGRAM' 

*********************************************************************** 

SPACE 4 LISTING CONTROL CARD - SPACE 4 

*********************************************************************** 

MESSAGE RETRIEVAL PROGRAM ENTRY 
MOVE RETRIEVE ALL INDICATOR 
MOVE DESTINATION IDENTIFICATION 
COMPARE ALL INDICATOR FOR ALL 

MOVE RETRIEVE ALL INDICATOR 

ALL INDICATOR 1 BYPASS 

COMPARE DEST IDENT TO BLANKS 

GO TO DEST ID = BL IF EQUAL 

MOVE DESTINATION IDENTIFICATION 

DESTINATION IDENT EQUALS BLANKS 
*********************************************************************** 

SPACE 4 LISTING CONTROL CARD - SPACE 4 

************************************ ************ ************ *********** 

MRPGTDN DS OH GET TRANSIENT DATA ENTRY 

MVC TCATDDI,TWATDDI MOVE DESTINATION IDENTIFICATION 

DFHTD TYPE=GET, * 

NORESP=MRPNRCN, * 

QUEZERO=MRPQERN, * 
IDERROR=MRPDIEN 

DFHPC TYPE=ABEND, * 
ABCODE=XMRP 
*********************************************************************** 

SPACE 2 LISTING CONTROL CARD - SPACE 2 

*********************************************************************** 

MRPNRCN DS OH NORMAL RESP CODE ENTRY ADDRESS 

L TDIABAR,TCATDAA LOAD TRANS DATA AREA ADDRESS 
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ALPMRPN 


DS 


OH 




MVC 


TWAREAI,TIOARAI2 




MVC 


TWATDDI,TCTTETI 




CLC 


^•ALL^TIOARAH 




BNE 


MRPAI1B 




MVC 


TWAREAI,TIOARAI1 




B 


MRPDEBN 


MRPAI1B 


DS 


OH 




CLC 


=CL4' «,TIOADID 




BE 


MRPDEBN 




MVC 


TWATDDI,TIOADID 


MRPDEBN 


DS 


OH 



DFHTC 


TYPE = (WAIT) 


MVC 


MRPMTDI+1 (1),TDIAIRL+1 


MRPMTDI MVC 


TIOATDL(O) /TDIAIRL 


LK 


14, TIOATDL 


SH 


14,=H»4» 


STH 


14, TIOATDL 


DFHTC 


TYPE= (WRITE, 




SAVE) 


CLC 


=CL3 »ALL , ,TWAREAI 


BNE 


RETURN 


MVI 


TWAQEMCIjX'FF 1 


B 


MRPGTDN 



MOVE DATA LENGTH TO MOVE INSTR 
MOVE TRANS DATA TO TERM AREA 
LOAD TERMINAL DATA LENGTH 
SUBTRACT 4 FROM LENGTH 
STORE TERMINAL DATA LENGTH 



COMPARE RETRIEVE ALL IND TO ALL 
GO TO RETURN ENTRY IF NOT EQUAL 
MOVE MESSAGE CONTROL INDICATOR 
GO TO GET TRANSIENT DATA ENTRY 

* * ******* **** *********************************************** *********** 

SPACE 4 LISTING CONTROL CARD - SPACE 4 

*********************************************************************** 

MRPQERN DS OH DESTINATION QUEUE EMPTY ENTRY 

CLI TWAQEMCI,X»FF B COMPARE MESSAGE CONTROL IND 

BE MRPNMQMB GO TO NO MSG QUEUED MSG BYPASS 

MVC TIOATDL (MRPNQML ) f MRPNMQM MOVE TERMINAL MESSAGE TO OUTPUT 

B MRPWRCS GO TO WRITE & RETURN TO C S 

MRPNMQMB DS OH NO MESSAGES QUEUED MSG BYPASS 

DFHTC TYPE= (WAIT) 

MVC TIOATDL (MRPNMML) ,MRPNMMM MOVE NO MORE MESSAGE TO T A 
*********************************************************************** 

MRPWRCS DS OH WRITE AND RETURN TO CONT SYS 

DFHTC TYPE= (WRITE) 

B RETURN GO TO RETURN ENTRY 

*********************************************************************** 

EJECT LISTING CONTROL CARD - EJECT 

*********************************************************************** 

* * * * 
*********************************************************************** 

DESTINATION IDENT ERROR ENTRY 

STORE TERM I/O AREA ADDRESS 

DESTINATION IDENT ERROR ENTRY 

DESTINATION IDENT ERROR ENTRY 

TIO&TDL (MCPDEML),MCPD IBM MOVE TERMINAL MESSAGE TO OUTPUT 

DFHTC TYPE= (WRITE) 
*********************************************************************** 

SPACE <J LISTING CONTROL CARD - SPACE 4 

RETURN DS OH RETURN TO CONTROL SYSTEM 

DFHPC TYPE=RETURN 
*********************************************************************** 

LTORG * LITERAL ORIGIN AT * 

*********************************************************************** 

END CICSATP END OF ASSEMBLY - APPL TEST PGM 



DCPDIEN 


DS 


OH 




ST 


TIOABAR,TCTTEDA 


MEPDIEN 


DS 


OH 


MRPDIEN 


DS 


OH 




MVC 


TIO&TDL (MCPDEML 
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*********#*:£«******##***#********************************************** 

COBOL EXAMPLE PROBLEM 

************)}:*** ************* *^c***** ************************ *********** 



ID DIVISION. 
PROGRAM-ID. 
ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORKING-STORAGE SECTION 



CICSATP, 



77 
77 

77 
77 



77 
77 



77 
77 
77 



VALUE 58. 

• DATA COLLECTION 
t 



HAS 



DCPDCAML PIC 99 COHP 

DCPDCAMD PIC X (58) VALUE 

1 BEEN REQUESTED AND IS ABOUT TO BEGIN . 
DCPEODML PIC 99 COMP VALUE 73. 

DCPEODMD PIC X (73) VALUE • THE DATA HAS BEEN R 

•ECEIVED AND DISPATCHED TO THE DESIGNATED DESTINATION 

i ■ m 

MELHEAML PIC 99 COMP VALUE 77. 

HEPBBAHD PIC X (77) VALUE 'YOUR MESSAGE HAS BEE 

•N RECEIVED AND DISPATCHED TO THE DESIGNATED DESTINAT 
•ION •. 



MRPNMML 
MRPNQML 
MCPDEML 



PIC 99 
PIC 99 
PIC 99 



COMP 
COMP 
COMP 



VALUE 68. 
VALUE 63. 
VALUE 64. 



01 MESSG1. 

03 MCPDIEH 
03 FILLER 
03 MESSAGE1 



PIC 99 
PIC 99 
PIC X(60) 



• IDENTIFICATION ERROR 



VALUE 60. 
VALUE ZERO. 



COMP 
COMP 
VALUE • 
- PLEASE RESUBMIT 



DESTINATION 



01 



* 
01 



MESSG2. 
03 MRPNMHH 
03 FILLER 
03 MESSAGE2 



PIC 99 
PIC 99 
PIC X (64) 



COHP 
COMP 
VALUE 



VALUE 64. 
VALUE ZERO, 



THERE ARE N 



•0 MORE MESSAGES QUEUED FOR THIS DESTINATION 



MESSG3. 
03 MRPNHQM 
03 FILLER 
03 MESSAGE3 



PIC 99 
PIC 99 
PIC X(59) 



COMP 
COMP 
VALUE 



VALUE 59. 
VALUE ZERO. 



THERE ARE N 



•0 MORE MESSAGES QUEUED FOR THIS DESTINATION 



LINKAGE SECTION. 



01 



01 



DFHBLLDS COPY 


DFHBLLDS. 






03 TCTTEAR 


PIC 


S9 (8) 


COM P . 


03 TIOABAR 


PIC 


S9(8) 


COHP. 


03 TDIABAR 


PIC 


S9(8) 


COMP. 


DFHCSADS COPY 


DFHCSADS. 







01 DFHTCADS COPY DFHTCADS. 

03 THATDDI PIC X (4) 

03 TWAREAI PIC X (4) 

03 THAQEMCI PIC S9 



COHP. 



01 DFHTCTTE COPY DFHTCTTE . 



01 DFHTIOA COPY DFHTIOA. 



03 


TIOADATA 


PIC X (80) . 


03 


FILLER 


REDEFINES TIOADATA. 




05 EODTEST 


PIC X (3). 




05 FILLER 


PIC X (77) . 


03 


FILLER 


REDEFINES TIOADATA. 
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05 


TIOATID PIC X(4) . 


05 


FILLER PIC X. 


05 


TIOADID PIC X(4) . 


05 


FILLER REDEFINES TIOADID. 




07 TIOARAI1 PIC X (3) . 




07 FILLER PIC X. 


05 


TIOARAI2 PIC X(3) . 


05 


FILLER REDEFINES TIOARAI2 




07 TIOAMBA PIC X. 




07 FILLER PIC XX. 


05 


FILLER PIC X (68). 


'DIA 


COPY DFHTDIA. 


TDIADBA PIC X (80) . 



01 DFl 
02 
* 

PROCEDURE DIVISION. 
************** 

ATPIPIN. 
************** 

MOVE CSACDTA TO TCACBAR. 
MOVE TCAFCAAA TO TCTTEAR. 
MOVE TCTTEDA TO TIOABAR. 



IF 


TIOATID = »BSDC» 


THEN 


GO TO ALPDCPN. 


IF 


TIOATID = •BSME» 


THEN 


GO TO ALPMEPN. 


IF 


TIOATID = »BSMR» 


THEN 


GO TO ALPMRPN. 



DFHPC TYPE=ABEND, 
ABCODE=XAPT 
* 
************** 

ALPDCPN. 
************** 

* DATA COLLECTION 

MOVE TIOADID TO TWATDDI. 
MOVE DCPDCAML TO TIOATDL. 
MOVE DCPDCAMD TO TIOADATA. 

DFHTC TYPE= (WRITE, RE AD, WAIT) 



DCPTEWN. 




MOVE 


TCTTEDA TO TIOABAR 


IF 


EODTEST = •EDO* 


THEN 


GO TO DCPEXIT. 


MOVE 


TWATDDI TO TCATDDI 


MOVE 


ZEROES TO TCTTEDA. 


ADD 


4 TO TIOATDL. 



DFHTD TYPE=P0T, * 

TDADDR=TIOATDL, * 

NORESP=DCPNRCN, * 
IDERROR=DCPDIEN 

DFHPC TYPE=APEND / * 
ABCODE=XDCP 



DCPNRCN. 
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MOVE 


TIOABAR TO TCASCSA. 


DFHSC 


TYPE=FREEMAIN 


DFHTC 


TYPE = (READ, WAIT) 


GO TO 


DCPTEWN. 


DCPEXIT. 




MOVE 


DCPEODML TO TIOATDL. 


ADD 


4 TO TIOATDL. 


MOVE 


DCPEODMD TO TIOADATA 


DFHTC 


TYPE=WRITE 


GO TO 


RETURN1. 



************** 

ALPHEPN. 
************** 

* MESSAGE ENTRY 
* 

MOVE TIOADID TO. TCATDDI. 

MOVE TCTTETI TO TIOATID. 

ADD 4 TO TIOATDL. 



DFHTD TYPE=PUT, 

TDADDR=TIOATDL, 
NORESP=MEPNRCN, 
IDERROR=MEPDIAN 



DFHPC TYPE=ABEND, 
ABCODE=XMEP 



MEPNRCN. 




MOVE 


MEPMEAML TO TIOATDL. 


ADD 


4 TO TIOATDL. 


MOVE 


MEPMEAMD TO TIORDATA 


DFHTC 


TYPE=WRITE 


GO TO 


RETURN 1. 



************** 

ALPMRPN. 
************** 

* MESSAGE RETRIEVAL 
* 

MOVE TIOARAI2 TO TWAREAI. 
MOVE TCTTETI TO TWATDDI. 

IF TIOARAI1 NOT = »ALL« 
THEN GO TO MRPAI1B. 

MOVE TIOARAI1 TO TWAREAI. 
GO TO MRPDEBN. 



MRPAI1B. 
IF 
THEN 



TIOADID = SPACES 
GO TO MRPDEBN. 



MOVE 



TIOADID TO TWATDDI. 



MRPDEBN. 

MRPGTDN. 

MOVE 



TWATDDI TO TCATDDI 



DFHTD TYPE=GET, 

NORESP=MRPNRCN, 

QUEZERO=MRPQERN / 

IDERROR=MRPDIEN 
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DFHPC TYPE=ABEND, 
ABCODE=XMRP 

MRPNRCN. 

MOVE TDIAIRL TO TIOATDL. 
MOVE TDIADBA TO TIOADATA. 
SUBTRACT 4 FROM TIOATDL. 
DFHTC TYPE= (WRITE, WAIT, SAVE) 

IF TWAREAI NOT = »ALL» 
THEN GO TO RETURN 1. 

MOVE 255 TO TWAQEMCI. 
GO TO MRPGTDN. 



MRPQERN. 
IF 
THEN 



TWAQEMCI = 255 
GO TO MRPNMQMB 



MOVE MRPNMQM TO TIOATDL. 
MOVE MESSAGE3 TO TIOADATA, 
GO TO MRPHRCS. 



MRPNMQMB. 
MOVE 
MOVE 



MRPNMMM TO TIOATDL. 
MESSAGE2 TO TIOADATA. 



MRPWRCS. 
DFHTC 
GO TO 



TYPE=WRITE 
RETURN1. 



DCPDIEN. 
MOVE 



TIOABAR TO TCTTEDA 



MEPDIEN. 

MRPDIEN. 
MOVE 
MOVE 
DFHTC 



HCPDIEM TO TIOATDL. 
HESSAGE1 TO TIOADATA 
TYPE=WRITE 



RETURN1. 

DFHPC TYPE=RETURN 
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*********************************************************************** 

PL/I EXAMPLE PROBLEM 

**************** ******************************************************* 

/* PL/I EXAMPLE PROBLEM */ 

DFHCOVER 
CICSATP: PROCEDURE OPTIONS (MAIN, REENTRANT) ; 
56INCLUDE DFHCSADS; 
% INCLUDE DFHTCADS; 

2 TWATDDI CHAR (4), 
2 TWARBAI CHAR (4) , 
2 THAQEMCI BINARY FIXED (8) ; 
^INCLUDE DFHTCTTE; 
%INCLUDE DFHTIOA; 

2 TIOADATA CHAR (80) ; 
DECLARE 1 TIOA1 BASED (TIOABAR), 
2 FILL1 CHAR (12) , 
2 TIOATID CHAR (4) , 
2 FILL2 CHAR (1) , 
2 TIOARAI1 CHAR (3), 
2 FILL3 CHAR (2) , 
2 TIOAMBA CHAR (1) ; 
DECLARE 1 TIOA2 BASED (TIOABAR), 
2 FILL1 CHAR (12) , 
2 EODTEST CHAR (3) , 
2 FILL2 CHAR (2) , 
2 TIOADID CHAR (4), 
2 F1LL3 CHAR (1) , 
2 TIOARAI2 CHAR (3) ; 
^INCLUDE DFHTDIA; 

2 TDIADBA CHAR (80) ; 
DCL MCPDEML FIXED BIN IN IT (56) , MCPDIEM CHAR (56) INITIAL 
(• DESTINATION IDENTIFICATION ERROR - PLEASE RESUBMIT 1 ); 

DCL DCPDCAML FIXED BIN INIT (57) , DCPDCAMD CHAR (57 ) INITIAL 
(» DATA COLLECTION HAS BEEN REQUESTED AND IS ABOUT TO BEGIN*) ; 
DCL DCPEODML FIXED BIN INIT (72) , DCPEODMD CHAR (72) INITIAL 
(• THE DATA HAS BEEN RECEIVED AND DISPATCHED TO THE DESIGNATED DESTINAT 
ION») ; 

DCL MEPMEAML FIXED BIN INIT (76) , MEPEAMD CHAR (76) INITIAL 
(• YOUR MESSAGE HAS BEEN RECEIVED AND DISPATCHED TO THE DESIGNATED DEST 
INATION') ; 

DCL HRPNMHL FIXED BIN INIT (60) , MRPNMMM CHAR (60) INITIAL 
(• THERE ARE NO MORE MESSAGES QUEUED FOR THIS DESTINATION 1 ); 

DCL MRPNQML FIXED BIN INIT (55), MRPNMQN CHAR (55) INITIAL 
(• THERE ARE NO MESSAGES QUEUED FOR THIS DESTINATION 1 ) ; 
ATPIPIN: TCTTEAR = TCAFCAAA; 
TIOABAR = TCTTEDA; 

IF TIOATID = «PSDC» THEN GO TO ALPDCPN; 
IF TIOATID = ■PSME' THEN GO TO ALPMEPN; 
IF TIOATID = »PSMR» THEN GO TO ALPMRPN; 
DFHPC TYPE=ABEND, * 

ABCODE=XAPT 
/* DATA COLLECTION PROGRAM */ 
ALPDCPN: TWATDDI = TIOADID; 
TIOATDL = DCPDCAML; 
TIOADATA = DCPDCAMD; 
DFHTC TYPE= (WRITE, READ, WAIT) 



DCPTEWN: 



TIOABAR = TCTTEDA; 

IF EODTEST = »EOD» THEN GO TO DCPEXIT; 
TCATDDI = TWATDDI; 
UNSPEC (TCTTEDA) = 0; 
TIOATDL = TIOATDL + 4; 
DFHTD TYPE=PUT, * 

TDADDR=TIOATDL, * 
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NORESP=DCPNRCN, * 

IDERROR=DCPDIEN 
DFHPC TYPT^ABEND, * 

ABCODE=XDCP 
DCPNRCN: TCASCSA = TIOABAR; 
DFHSC TYPE=FREEMAIN 
DFHTC TYPE= (READ, WAIT) 
GO TO DCPTEWN; 
DCPEXIT: TIOATDL = DCPEODML; 
TIOADATA = DCPEODMD; 
DFHTC TYPE=WRITE 
GO TO RETURN; 
/* MESSAGE ENTRY PROGRAM */ 
ALPMEPN: TCATDDI = TIOADID; 
TIOATID = TCTTETI; 
TIOATDL = TIOATDL + 4; 
DFHTD TYPE=PUT, * 

TDADDR=TIOATDL, * 

NORESP=MEPNRCN, * 

IDERROR=MEPDIEN 
DFHPC TYPE=ABEND, * 

ABCODE=XMEP 
MEPNRCN: TIOATDL = MEPMEAML; TIOADATA = MEPEAMD; 
DFHTC TYPE=WRITE 
GO TO RETURN; 
/* MESSAGE RETRIEVAL PROGRAM */ 
ALPMRPN: TWAREAI = TIOARAI2; TWATDDI = TCTTETI; 

IF TIOARAI1 ->= 'ALL* THEN GO TO MRPAI1B; 
TWAREAI = TIOARAI1; 
GO TO MRPDEBN; 
MRPAI1B: IF TIOADID = « ■ THEN GO TO MRPDEBN; 

TWATDDI = TIOADID; 
MRPDEBN: MRPGTDN: TCATDDI = TWATDDI; 

DFHTD TYPE=GET, * 

NORESP=MRPNRCN, * 

QUEZERO=MRPQERN, * 

IDERROR=MRPDIEN 
DFHPC TYPE=ABEND, * 

ftBCODE=XMRP 
MRPNRCN: TDIABAR = TCATDAA; 

TIOATDL = TDIAIRL - 4; 
TIOADATA = TDIADBA; 
DFHTC TYPE= (WRITE, WAIT , SAVE) 

IF TWAREAI -1= »ALL« THEN GO TO RETURN; 
TWAQEMCI = '11111111 »B; 
GO TO MRPGTDN; 
MRPQERN: IF TWAQEMCI = •11111111 , B THEN GO TO MRPNMQMB; 
TIOATDL = HRPNQML; 
TIOADATA = MRPNMQN; 
GO TO MRPWRCS; 
MRPNMQMB: TIOATDL = MRPNMML; TIOADATA = MRPNMMM; 
MRPWRCS: 

DFHTC TYPE=WRITE 
GO TO RETURN; 
DCPDIEN: TCTTEDA = TIOABAR; 
MEPDIEN: MRPDIEN: TIOATDL = MCPDEML; 
TIOADATA = MCPDIEM; 
DFHTC TYPE=WRITE 
RETURN: 

END CICSATP; 
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Appendix B. BMS Map Definition Example 



This appendix shows the BMS map definition macro instructions used to 
generate the symbolic storage definition associated with an input map 
for a display with the format shown below. The appendix also shows, for 
each programming language, the symbolic storage definition that is 
generated by the macro instructions. 



□ PAYROLL 



□ NAME: 



□ DATE: 



□ SEX: 



□ MMDDYY 



□ ?MALE 



□ SKILLS: □ 



□ PAY: 



The following map definition macro instructions would be used to 
create the symbolic storage definition (DSECT) associated with an input 
map for an assembler language application program. {To create the map 
itself, the TYPE=DSECT operand would be replaced by a TYPE=MAP operand.) 



MAPSET 


DFHMSD 


MAPI 


DFHMDI 




DFHMDF 




DFHMDF 


NAME 


DFHMDF 




DFHMDF 


MONTH 


DFHMDF 


DAY 


DFHMDF 


YEAR 


DFHMDF 




DFHMDF 


SEX 


DFHMDF 




DFHMDF 


SKILLS 


DFHMDF 




DFHMDF 


PAY 


DFHMDF 




DFHMSD 




END 



TYPE=DSECT,MODE=IN,CTRL= (FREEKB ,FR SET) , 
LANG=ASM,EXT&TT=MAPONLY - 

LINE=1,C0LUMN=1,JUSTIFY= (LEFT, FIRST) 

POS=9,LENGTH=7,INITIAL= , PAYROLL»,ATTRB=BRT, 
HILIGHT=UNDERLINE 

POS=40,LENGTH=8,INITIAL=«NAME: • 

POS=49,LENGTH=20,ATTRB=IC,COLOR=RED 

POS=80,LENGTH=8,INITIAL='DATE: • 

POS=89,LENGTH=2,GRPNAME=DATE,INITIAL= , MM» ,ATTRB=NUM 

P0S=91,LENGTR=2,GRPNAME=DATE,INITIAL= , DD I , 
JUSTIFY= (LEFT, BLANK) 

POS=93,LENGTH=2,GRPNAME=DATE,INITIAL=»YY» 

POS=120,LENGTH=8,INITIAL=»SEX: • 

POS=129,LENGTH=5,ATTRB=DET,INITIAL=»?MALE» 

POS=16 0,LENGTH=8,INIT1AL=»SKILLS:» 

POS= 169 ,LENGTH=4 , ATTRB=UNPROT ,0CCURS=3 

POS=200,LENGTH=8,INITIAL=»PAY: • 

POS=209,LENGTH=6,ATTRB=NUM,COLOR=BLUE 

TYPE=FINAL 
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The assembler DSECT produced as a result of the above statements 
would be as follows: 



MAPII DS OC 

SPACE 
NAMEL DS CL2 
NAMEF DS OC 

DS C 
NAMEI DS CL20 
SPACE 
START NEW DATA GROUP DATE 
CL2 
OC 
C 

OC 
2 
CL2 



DATEL 
DATEF 



DATEI 



DS 

DS 

DS 

DS 

SPACE 

DS 
SPACE 

DS 
SPACE 

DS 
SPACE 

DS 

DS 

DS 

DS 
SPACE 

DS 

DS 

DS 

DS 

DS 

EQU 

ORG 
SPACE 

DS 

DS 

DS 

DS 
SPACE 
END OF MAP DEFINITION * * * 

SPACE 3 

ORG 
MAPSETT EQU * * END OF MAPSET 

* * * END OF MAP SET DEFINITION * * * 

SPACE 3 



MONTHI 

DAYI 

YEARI 

SEXL 
SEXF 

SEXI 

SKILLSD 
SKILLSL 
SKILLSF 

SKILLSI 
SKILLSN 



PAYL 
PAYF 

PAYI 
* * * 



CL2 

CL2 

CL2 
OC 
C 
CL1 

OC 

CL2 

OC 

C 

CLU 

* 

SKILLSD+3* (3+U) 

CL2 
OC 
C 
CL6 



INPUT DATA FIELD LENGTH 
DATA FIELD FLAG 
DATA FIELD ATTRIBUTE 
DATA FIELD 



INPUT GROUP FIELD LENGTH 
GROUP FIELD FLAG 
GROUP FIELD ATTRIBUTE 
GROUP FIELD ORIGIN 

DATA FIELD 

DATA FIELD 

DATA FIELD 

INPUT DATA FIELD LENGTH 

DATA FIELD FLAG 

DATA FIELD ATTRIBUTE 
DATA FIELD 

FIRST OCCURRING FIELD 

INPUT DATA FIELD LENGTH 

DATA FIELD FLAG 

DATA FIELD ATTRIBUTE 

DATA FIELD 

NEXT OCCURRING FIELD 

ALLOCATE OCCURRING FIELD SPACE 

INPUT DATA FIELD LENGTH 
DATA FIELD FLAG 
DATA FIELD ATTRIBUTE 
DATA FIELD 
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By changing LANG=ASM to LANG=COBOL in the DFHMSD macro, the following 
symbolic storage definition could be produced. 



01 MAPII. 

02 NAMEL COUP PIC S9 (4) . 

02 NAMEF PIC X. 

02 NAMEI PIC X (20) . 

02 DATEL COMP PIC S9 (4) . 

02 DATEF PIC X. 

02 DATEI. 

03 MONTHI PIC X(2) . 

03 DAYI PIC X(2) . 

03 YEARI PIC X(2) . 
02 SEXL COMP PIC S9 (4) . 
02 SEXF PIC X. 
02 SEXI PIC X(1) . 
02 SKILLSD OCCURS 3 TIMES. 

03 SKILLSL COMP PIC S9 (4 ) . 

03 SKILLSF PIC X. 

03 SKILLSI PIC X (4) . 
02 PAYL COMP PIC S9(4). 
02 PAYF PICE X. 
02 PAYI PIC X (6) . 

Similarly, changing LANG=ASM to LANG=PLI in the DFHMSD macro would 
produce the following symbolic storage definition: 

DECLARE 1 MAPII BASED (BMSMAPBR) UNALIGNED, 
2 NAMEL FIXED BIN (15,0), 
2 NAMEF CHAR(1) , 
2 NAMEI CHAR (20) , 
2 DATEL FIXED BIN (15,0), 
2 DATEF CHAR (1) , 
2 DATEI , 

3 MONTHI CHAR (2) , 

3 DAYI CHAR (2) , 

3 YEARI CHAR (2), 
2 SEXL FIXED BIN (15,0), 
2 SEXF CHAR (1) , 
2 SEXI CHAR(1) , 
2 SKILLSD (3), 

3 SKILLSL FIXED BIN (15,0), 

3 SKILLSF CHAR (1) , 

3 SKILLSI CHAR (4), 
2 PAYL FIXED BIN (15,0), 
2 PAYF CHAR(1) , 
2 PAYI CHAR (6) , 
2 FILL0024 CHAR (1); 
/* END OF MAP DEFINITION */ 
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Appendix C. Inter-Release Compatibility 



This appendix defines any incompatibilities that exist between the 
I application programming interface (API) for CICS/VS Version 1.5 and 
| Versions 1.1.0, 1.1.1, 1.2, 1.3, 1.4, and 1.4.1. Such incompatibilities 
| can be divided into two categories: source incompatibilities, that is, 
| input code that CICS/VS Version 1.5 will treat differently from previous 
versions of CICS/VS, thus producing a different object program; and 
object incompatibilities, that is, differences in the results that will 
be obtained when the same object program is executed under CICS/VS 
I Version 1.5 from those obtained running under earlier versions. 

There are no incompatibilities between Versions 1.4 and 1.4.1. 



Source Incompatibilities 

In versions of CICS/VS previous to 1.4, it has not been valid to code 
TIOAPFX=YES in the DFHMSD or DFHttDI macro instruction for an assemaler 
language application program. If this operand was coded in this way, 
CICS/VS disregarded it and applied the default specification 
| (TI0APFX=N0) . In CICS/VS Versions 1.4, 1.4.1, and 1.5, it is valid to 
| code TIOAPFX=YES for an assembler program: doing so will thus produce 
different object program under CICS/VS 1.4, 1.4.1, or 1.5 from that 
which would be produced under earlier versions. 

There are no other source incompatibilities. 



O bject Incompatibilitie s 

There are no object incompatibilities. 

D efinition of the Application Programmer Interface 

The remainder of this appendix defines the application programming 
interface that applies to users converting from Versions 1.1.0, 1.1.1, 
| 1.2, 1.3, 1.4, or 1.4.1 of CICS/VS to Version 1.5 of CICS/VS. 

The API is defined as the CICS/VS macro instructions, control block 
fields, and area prefix fields that are available for use by a user- 
written application program. With the exception of the single source 
incompatibility (TIOAPFX=YES when LSNG=ASM) described above, application 
programs using these macros or fields will execute successfully under 
I Versions, 1.4, 1.4.1, and 1.5 without recompilation. 

The macros and fields of the API that are valid for a given release 
are those documented in the C ICS/VS Application Programmer's Reference 
Manual (Macro Leve l) for that release. References to fields or macros 
other than those documented in the manual, or to fields marked "unused" 
or "reserved" in former releases, may cause problems. Application 
programs containing such references should be recompiled, tested, and 
where necessary modified to ensure correct execution. 
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Users should also refer to the "Memorandum to Users" distributed with 
Version 1.5 for a further discussion of compatibility, particularly with 
respect to BMS maps. 



CICS/VS Macro Instructions 



The following macro instructions are those that are valid for Version 
1.4 and 1.4.1 of CICS/VS, and for which compatibility can be guaranteed 
for Version 1.5 for uses that were valid in Versions 1.4, and 1.4.1. 
They are documented in the CICS/VS Version 1, Release 4 Application 
P rogrammer's Reference Manual (Macro— Level) , Order No. SC33-0079— 1. 



DFHBIF 


DFHKC 


DFHTR 


DFHBMS 


DFHMDF 


DFHTS 


DFHDC 


DFHPC 




DFHDI 


DFHSC 




DFHFC 


DFHSP 




DFHIC 


DFHTC 




DFHJC 


DFHTD 





The CICS/OS/VS CALLDLI macro is also part of the API for Versions 1.4 
and 1.4.1. 

Only the operands and parameters of the macros described in the 
publication cited above are supported by CICS/VS for use by user— written 
application programs. 



CICS/VS Control Block Fields and Area Prefix Fields 



Many of the fields in CICS/VS areas, for example, the CSA, or prefixes 
to user I/O areas, for example, a TIOA, are referred to directly when a 
CICS/VS macro is executed and it is essential that their location, type, 
and meaning remain unchanged across releases. 

The following fields form the API for Version 1.5 of CICS/VS. Those 
marked with an asterisk were introduced in Version 1.5. Those that are 
not marked with an asterisk form the API for Version 1.4 and are 
referred to throughout the APRM for Version 1.4. 
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CSABFNAC — Address of built— in functions 

CSABMS - BMS address 

CSACDTA — Common System Area Currently Dispatched Task Address 

CSACTODB — Common System Area Current Time of Day in Binary format 

CSADCNAC — Dump Control Entry Address 

CSAFCNAC — File Control Entry Address 

CSAICNAC — Time Control Entry Address 

CSAICRNX — NOP/Branch Flush Routine Interface 

CSAJCNA1 — Journal Control Macro Entry Pointer 1 

CSAJCNA2 — Journal Control Macro Entry Pointer 2 

CSAJYDP — Common System Area Date in Packed decimal format 
(000YYDDD) 

CSAKCNAC - Task Control Entry Address 

CSAOPFLA — Common System Area Optional Features List Address 

CSAPCNAC — Program Control Entry Address 

CSASCNAC — Storage Control Entry Address 

CSASPNAC — Sync Point Program Entry Address 

CSATCNAC — Terminal Control Entry Address 

CSATCRWE - Terminal Control Read/Write Entry Address 

CSATDNAC — Transient Data Control Entry Address 

CSATODP — Common System Area Time of Day in Packed decimal format 
(four bytes) 

CSATRMF1 — Trace Master Flags 

CSATRMF2 — Trace System Flags 

CSATRMF3 - Trace System Flags 

CSATRNAC - Trace Control Entry Address 

CSATRTBA — Common System Area TRace TaBle Address 

CSATSNAC — Temporary Storage Entry Address 

CSAWABA — Common System Area Work Area Beginning Address 

FCDSOID — Beginning Address Data Area 

FCFIOBEX — File Control File Input/Output BDAM Error Code 
(four bytes) 

FCFIOEX - File Control File Input/Output ISAM Error Code 
(four bytes) 

FCFIOFCT — File Control Entry Table Address 
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FCFIOLRA — Logical Record Address 

FCUFCTA - File Control Table Entry Address 

FCOPDRA - File Input/Output Area Address 

FCUWA — File Control Update Work Area (data begin address) 

FIOADBA — Data Beginning Address 

FIOAIND - File I/O Area Indicator 

FWAIND - File Work Area Indicator 

JCAADATA — Journal Control Area Address of DATA to be written to 
journal data set 

JCAAPRFX — Journal Control Area Address of User-Prefix Data 

JCAECN — Journal Control Area Event Control Number 
(four bytes) 

JCAJCRC — Journal Control Area Journal Control Response Code 
(one byte) 

JCAJFID — Journal Control Area Journal File IDentif ication 
(one byte ) 



JCAJRTID - 

JCALDATA - 

JCALPRFX - 

JCANOTE 
JCARST 

JCATR1 - 

JCATR2 - 

JCATR3 - 

JCAVCD - 

JCAVSN - 

SAASACA - 

SAASAD - 

SAASCI - 

SAASFI - 

TCAATAC - 

TCABFPAM - 



Journal Control Area Journal Record Type IDentif ication 
(two bytes) 

Journal Control Area Length of DATA to be written to 
journal data set (two bytes) 

Journal Control Area Length of user PReFiX 
(two bytes) 

Note Request Returned— Data 

Run Start Time (HHMMSSS+) 

Type Reguest Bytel 

Type Request Byte2 

(Reserved for CICS usage) 

Volume Creation Date (YYDDD+) 

Volume Seguence Number (NNN+) 

Storage Accounting Area Storage Accounting Chain 
Address 

Storage Area Displacement 

Storage Class Identification 

Storage Format Identification 

Abnormal Termination Abend Code 

Address Pointer Initialization (Built— In Functions) 
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TCABFTR — Task Control Area Built-in Function Type of Request 
(one byte) 

TCABITF — Task Control Area BIT Manipulation address of one— byte 
bit Field to be operated on 

TCABITR — Task Control Area BIT Manipulation Result of BITEST 
operation (one byte) 

TCABITTP - Bit Function Type Indicator 

TCABITV — Task Control Area BIT Manipulation address of bit pattern 
(mask) to be applied to a specified byte 



TCABMSCP - 



Task Control Area basic mapping support Cursor Position 
(two bytes) 



TCABMSMA — Task Control Area basic mapping support Map Address 

TCABMSMN — Task Control Area basic mapping support Map Name 
(eight bytes) 

TCACCCA — Task Control Area Common Control Communication Area 

TCACCSV1 - Save Area for Bytes Overlaid by DFHDC 

TCACCSV2 — Save Area for Bytes Overlaid by DFHDC 

TCACHKR — Response Indicator (Built-in Function) 

TCACKFD — Task Control Area Field Verify address of FielD to be 
ChecKed 

TCACKLN — Task Control Area Field Verify LeNgth of field to be 
ChecKed (two bytes) 

TCADCDC - Task Control Area Dump Control Dump Code (four bytes) 

TCADCNB — Task Control Area Dump Control Number of Bytes in area to 
be dumped (two bytes) 

TCADCSA — Task Control Area Dump Control Storage Address of area to 
be dumped 

TCADCTR — Task Control Area Dump Control Type of Request (Assembler 
or PL/I; two bytes) 

TCADIDNA - Task Control Area Batch Data Interchange Destination 
Name Address 

TCADIKYA — Task Control Area Batch Data Interchange Key Address 

TCADINRS — Task Control Area Batch Data Interchange Number of 
Records in Request (one byte) 



TCADIRNA - 

TCADIVNA - 

TCADLFUN - 

TCADLIO - 



Task Control Area Batch Data Interchange Relative 
Record Number Address 

Task Control Area Batch Data Interchange Volume 
Name Address 

Task Control Area DL/I FUNction (four bytes) 

Task Control Area DL/I Input/Output area address 
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TCADLPCB — Task Control Area DL/I Program Control Block address 

TCADLPSB — Task Control Area DL/I program specification block name 
(eight bytes) 

TCADLSSA — Task Control Area DL/I address of segment search argument 
list 

TCADLTR — DL/I Type of Invalid Response 

TCAFCAA — Task Control Area File Control Area Address 

TCAFCAAA — Task Control Area Facility Control Area Associated 
Address 

TCAFCAI — Task Control Area File Control indirect Access data set 
Identification (eight bytes) 

TCAFCDI — Task Control Area File Control Data set Identification 
(eight bytes) 

TCAFCI — Facility Control Indicator 

TCAFCNRD — Task Control Area File Control Number of Records 
Deleted (two bytes binary) 

TCAFCRI — Task Control Area File Control record identification 
(eight bytes) 

TCAFCSI — Task Control Area File Control Segment Identification 
(eight bytes) 

TCAFCTR — Task Control Area File Control Type of Request/Response 
(Assembler or PL/I; one byte) 



TCAFCURL - 

TCAFLD - 

TCAFLN - 

TCAICCLS - 

TCAICDA - 

TCAICQID - 

TCAICQPX - 

TCAICRT - 

TCAICTEC - 

TCAICTI - 

TCAICTID - 



Task Control Area File Control Undefined Record 
Length (two bytes) 

Task Control Area Field Edit address of FieLD to be edited 

Task Control Area Field Edit LeNgth of Field to be 
edited (two bytes) 

Unique Identification of Request Identification 

Task Control Area Interval Control Data Area 

Task Control Area Interval Control reQuest 
IDentification (eight bytes) 

Task Control Area Interval Control 
reQuest Prefix (two bytes) 

Task Control Area Interval Control Request Time 
(four bytes) 

Task Control Area Interval Control Timer Event Control 
area address 

Task Control Area Interval Control Transaction 
Identification (four bytes) 

Task Control Area Interval Control Terminal 
IDentification (four bytes) 
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TCAICTR — Task Control Area Interval Control Type of Request/Response 
(Assembler or PL/I; one byte) 

TCAINAM — Name List Indicator 

TCAINA1 — Task Control Area IHput Formatting Address of list 
of offsets for the internal fixed— format TIOA 

TCAINA2 — Task Control Area IHput Formatting Address of list 
of field names that may appear in input stream 

TCAINH1 — Task Control Area IHput Formatting length of the TIOA 

to be acquired for the internal fixed— format representation 
of data (Halfword field) 

TCAINRC — Task Control Area IHput Formatting Response Code 
(one byte) 

TCAJCAAD — Task Control Area Journal Control Area ADdress 

TCAKCFA — Task Control Area Task Control (KCP) Facility control 
area Address 

TCAKCRC — System Macro Return Code 

TCAKCTA — Task Control Area Task Control (KCP) TCA Address 

TCAKCTI — Task Control Area Task Control (KCP) Transaction 
Identification (four bytes) 



TCAMSFMP - 



TCAHSFSC - 
TCAMSHDR - 

TCAMSIOA - 



Task Control Area Happing Support Function 
Management Parameter 

Field Separator Characters 

Task Control Area Happing Support HeaDeR address 
(four bytes) 

Task Control Area Happing Support Input/Output Area 
Address 

TCAMSJ — Task Control Area Happing Support Justification 
(one byte) 

TCAMSLDC — Logical Device Code 

TCAMSLDM - LDC Mnemonic 

TCAMSMSA — Task Control Area Mapping Support Map Set Address 

TCAMSMSN — Task Control Area Mapping Support Map Set Name 
(eight bytes) 

TCAMSOC — Task Control Area Mapping Support Operator Class 
(three bytes) 

TCAMSOCN — Overflow Control Number 

TCAMSPGN — Task Control Area Mapping Support PaGe Number 
(current page; two bytes binary) 

TCAMSRC1— — Task Control Area Mapping Support Response Code (one 
TCAMSRC3 byte each) 



TCAMSRID — Task Control Area Mapping Support Request IDentification 
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TCAMSRI1 - 



TCAMSRLA - 



Task Control Area Mapping Support Return Information 
(one byte) 

Task Control Area Mapping Support Routing List 
Address, or Returned page List Address 

TCAMSRTI — Task Control Area Mapping Support Routing 

Time or Time interval Indicator (four bytes packed decimal) 

TCAMSTA — Task Control Area Mapping Support Title Address 

TCAMSTI — Task Control Area Mapping Support error Terminal 
Identification (four bytes) 

TCAMSTRL — Task Control Area Mapping Support TRaiLer address 
(four bytes) 

TCAMSTR1— — Task Control Area Mapping Support Type Request (one 
TCAMSTR7 byte each) 

TCAMSWCC — Write Control Characters 

TCANAME — Task Control Area Phonetic Conversion 16-byte field 
containing data (NAME) to be phonetically encoded 

TCANXTID — Task Control Area Next Transaction IDentif ication 
(four bytes) 

TCAOCLA - Open/Close List Address 

TCAOCTR — Open/Close Type of Request 

TCAPCAC - Task Control Area Program Control ABEND Code 
(four bytes) 

TCAPCARO — Abend Recovery Option 

TCAPCERA — Task Control Area Program Control Exit Routine Address 

TCAPCLA — Loaded Program Beginning Address 

TCAPCPI — Task Control Area Program Control Program Identification 
(eight bytes) 

TCAPCPSH — System Recovery Program PSW 

TCAPCSR — Program Control Secondary Request 

TCAPCTR — Type of Request/Response 

TCAPHNR — Task Control Area PHoNetic Conversion error Response 
indicator (contains X 9 5i\* if invalid name was 
encountered; one byte) 

TCAPHON — Task Control Area PHONetic Conversion 4-byte returned 
value 

TCAPORGI - Task Purge Indicator 

TCASCIB - Task Control Area Storage Control Initialization Byte 

TCASCNB - Task Control Area Storage Control Number of Bytes 
of storage requested (two bytes) 

TCASCSA — Task Control Area Storage Control Storage Address 
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of area acquired or to be freed 

TCASCTR - Storage Control Type of Reguest 

TCASPTR — Sync Point Reguest 

TCASVMID — Service Module Control Indentif ication 

TCATCDC — Task Control Area Task Control Dispatcher Control 
indicator (one byte) 

TCATCDP — Task Control Area Task Control Dispatching Priority 
(one byte) 

TCATCEA — Task Control Area Task Control Event control area 
Address (ECB or CCB or list) 

TCATCEI — Task Control Event Control Indicator 

TCATCQA — Task Control Area Task Control enQueued resource length 
(high— order byte) and Address (three low— order bytes) 

TCATCTR — Task Control Type of Reguest 

TCATDAA — Task Control Area Transient Data Area Address 

TCATDDI — Task Control Area Transient Data Destination 
Identification (four bytes) 

TCATDTR — Task Control Area Transient Data Type of Reguest/Response 
(Assembler or PL/I; one byte) 

TCATPAPR — Application Reguest Response Code 

TCATPCON — Connection Type Flag 

TCATPCS1 — External Control Reguest Byte 1 

TCATPCS2 — External Control Reguest Byte 2 

TCATPLDA — Logic Device Code Entry Address 

TCATPLDC — Logical Device Code 

TCATPLDM — Logical Device Mnemonic 

TCATPLRC — Locate Return Code 

TCATP0C2 — Operation Control Byte 2 

TCATP0C3 — Operation Control Byte 3 

TCATP0S1 — External Operation Reguest Byte 1 

TCATP0S2 — External Operation Reguest Byte 2 

TCATPPNM — Program Name Field 

TCATPTA — Terminal Address or Identification 

TCATRF1 — Trace Entry Data Area 1 

TCATRF2 — Trace Entry Data Area 2 

TCATRID — Trace Entry Identification 
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TCATRID1 — Trace Entry Identification Extension 

TCATRHF - TCA Trace Control (Single Task) 

TCATRTR — Type of Trace Request 

TCATSAF — Task Control Area Table Search length of Field in 

Argument table entry to be compared with search argument 
(one byte) 

TCATSA1 — Task Control Area Table Search Address of search argument 

TCATSA2 — Task Control Area Table Search Address of first entry in 
argument table 

TCATSA3 — Task Control Area Table Search Address of first function 
table entry 

TCATSA4 — Task Control Area Table Search Address of field in first 
entry in argument table to be compared with search 
argument 

TCATSA5 — Task Control Area Table Search Address of (1) function 

field within first function table entry , on input, or (2) 
function field within function table entry which 
contained value retrieved, on output 

TCATSDA — Task Control Area Temporary Storage Data Address 

TCATSDI — Task Control Area Temporary Storage Data Identification 
(eight bytes) 

TCATSFC — Function Code (Built— In Function) 

TCATSFF - Task Control Area Table Search length of Field in 
Function table entry to be retrieved (one byte) 

TCATSH1 — Task Control Area Table Search maximum number of entries 
to be searched (halfword) 

TCATSH2 — Task Control Area Table Search length of each argument 
table entry (halfword) 

TCATSH3 — Task Control Area Table Search length of each function 
table entry (halfword) 

TCATSH4 — Task Control Area Table Search index value (relative to 

1) identifying the matching argument table entry returned 
to application program; if zero, no matching entry was 
found (halfword) 

TCATSRN — Task Control Area Temporary Storage Record Number 

TCATSRPC — Task Control Area Table Search Response Code 

TCATSTR — Task Control Area Temporary Storage Type of 

Request/Response (Assembler or PL/I; one byte) 

TCATSTR2 — Type of Request (Secondary) 

TCAWGAA - Task Control Area WeiGhted Retrieval VSWA pointer 

TCAWGCNT — Task Control Area Weighted Retrieval Count of maximum 
number of records to be made available to application 
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program; NRECDS parameter (halfword field) 

TCAWGH1 — Task Control Area HeiGhted Retrieval highest percentage 
of acceptability for a weighted retrieval function 
(halfword) 

TCAWGH2 — Task Control Area HeiGhted Retrieval lowest percentage of 
acceptability for a weighted retrieval function 
(halfword) 

TCAWGH3 — Task Control Area WeiGhted Retrieval percentage of 

acceptability of this record saved as the result of a 
weighted retrieval operation (Halfword field) 

TCAWGH4 — Task Control Area WeiGhted Retrieval number of records 
left to be presented to user (Halfword field) 

TCAHGH5 — Task Control Area WeiGhted Retrieval number of records 

dropped to remain within user-specified maximum (NRECDS) 
(Halfword field) 

TCAWPAA - VSWA Pointer 

TCAWPA1 — Task Control Area Weighted Retrieval Address of search 
argument 

TCAWPA3 — Task Control Area Weighted Retrieval Address of area 
containing record to be examined 

TCAWPA4 — Task Control Area Weighted Retrieval Address of field 
within area containing record to be examined 

TCAWPB1 — Task Control Area Weighted Retrieval character indicating 
format of search argument (one byte) 

TCAWPH1 — Task Control Area Weighted Retrieval length of search 
argument (halfword) 

TCAWPH2 — Task Control Area Weighted Retrieval match value 
(halfword) 

TCAWPH3 — Task Control Area Weighted Retrieval no match value 
(halfword) 

TCAWPH4 — Task Control Area Weighted Retrieval upper limit of 
comparison range (halfword) 

TCAWPH5 — Task Control Area Weighted Retrieval lower limit of 
comparison range (halfword) 

TCAWPNL — Task Control Area Weighted Retrieval NulL character 
(one byte) 

TCAWPTR — Task Control Area Weighted Retrieval Type of Range 
(one byte) 

TCAWRAA — Task Control Area Weighted Retrieval VSWA pointer 

TCAWTDI — Task Control Area Weighted ReTrieval Data Identification 
(eight bytes) 

TCAWTH1 — Task Control Area Weighted ReTrieval maximum number 
of records to be retrieved (halfword) 
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TCAWTH2 — Task Control Area Weighted ReTrieval relative number 
of record with same partial key to be examined first 
(half word) 

TCAWTH3 — Task Control Area Weighted ReTrieval maximum percentage 
of acceptability for retrieved records (half word) 

TCABTH4 — Task Control Area Weighted ReTrieval minimum percentage 
of acceptability for retrieved records (halfword) 

TCAWTRC — Task Control Area Weighted Retrieval Response Code 
(one byte) 

TCAWTRI — Task Control Area Weighted ReTrieval address of partial 
key of Record at which retrieval is to begin (fullword) 

TCTEASCC — 3270 Alternate Screen Size (Columns) 

TCTEASCL — 3270 Alternate Screen Size (Rows) 

TCTEASCZ - 3270 Alternate Screen Size 

TCTEDSCC - 3270 Default Screen Size (Columns) 

TCTEDSCL - 3270 Default Screen Size (Rows) 

TCTEDSCZ - 3270 Default Screen Size 

TCTEEOCI — EOC or OC Received Indicator 

TCTEFMHI - FMH Area for 3600 Devices 

TCTESIDI - Field containing inbound SIGNAL data (4 bytes) 

TCTESIDO - Area for Outbound Signal Data 

TCTETDST — Data Stream Type Byte 

TCTETXTF - 3270 Text Feature Flag byte (APL/TEXT) 

TCTEVLDC — Logical Device Code 

TCTE32EF - * 3270 Data Stream Extensions Flag 

TCTE32SF - 3270 Screen Size Flag 

TCTTEAID — Terminal Control Table Terminal Entry Attention 

IDentifier (used with the 3270 Information Display 
System; one byte) 

TCTTEBMN - Name of Format Image in Buffer 

TCTTECAD — Cursor Address in Binary 

TCTTECIA - Terminal Control Table Terminal Entry Control 
Information Area pointer 

TCTTECIL - Length of User Area 

TCTTECR — Request Completion Analysis 

TCTTECRE — Request Completion Extension 

TCTTEDA - Terminal Control Table Terminal Entry Data Address 
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TCTTEDES 
TCTTEFIB 
TCTTEOCL 
TCTTEPCF 

TCTTESC 
TCTTESID 



TCArt Destination Name 

Terminal Feature Flag Byte 

Operator Class Code 

Terminal Control Table Terminal Entry Passbook Control 
Field (2980 General Banking Terminal System; one byte) 



TCTTETAB - 



Terminal Storage Chain Address 

Terminal Control Table Terminal Entry Station 
IDentif ication (2980 General Banking Terminal System; 
one byte) 

Terminal Control Table Terminal Entry TABs needed to 
position print element (2980 General Banking Terminal 
System; one byte) 

TCTTETCM — TCAM Operation Code Flag 

TCTTETI — Terminal Identification 

TCTTETID — Terminal Control Table Terminal Entry Teller 

IDentif ication (2980 General Banking Terminal; one byte) 

TCTTETM — Terminal Control Table Terminal Entry Terminal Model 
(one byte) 

TCTTETS — Terminal Status 

TCTTETT — Terminal Control Table Terminal Entry Terminal Type 
(one byte) 

TDIADBA — Transient Data Input Area Data Begin Address 

TDIAIRL — Transient Data Input Area Intrapartition Record 
Length (two bytes) 

TDIASAL — Storage Accounting Area Length 

TDIASCA — Transaction Storage Chain Address 

TDOADBA — Transient Data Output Area Data Begin Address 

TDOASAL — Storage Accounting Area Length 

TDOASCA — Transaction Storage Chain Address 

TDOAVRL — Transient Data Output Area Variable Record Length 
(two bytes) 



TIOACLCR - 



Terminal Input/Output Area ControL CharacteR (same as 
TIOALAC; one byte) 



TIOADBA — Terminal Input/Output Area Data Begin Address 

TIOALAC — Terminal Input/Output Area Line Address Control 
(same as TIOACLCR; one byte) 

TIOATDL — Terminal Input/Output Area Transmission Data Length 
(two bytes) 

TIOAWCI - Write Control Indicator 
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TSIOADBA 
TSIOASAL 
TSIOASCA 
TSIOAVRL 

VSWAERRC 

VSWAID 

VSWALEN 

VSWAREA 

VSWARTNC 



Temporary Storage Input/Output Area Data Begin Address 

Storage Accounting Area Length 

Transaction Storage Chain Address 

Temporary Storage Input/Output Area Variable Record 
Length (two bytes) 

Error Code 

RPL Identifier 

VSAM Work Area record LENgth (four bytes) 

VSAM Work Area REcord Address 

RPL Return Code 
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Appendix D. Translation Tables for the 2980 



This appendix contains translation tables for the following components 
of the IBM 2980 General Banking Terminal System: 

• 2980 Teller Station Model 1 

• 2980 Administrative Station Model 2 

• 2980 Teller Station Model 4 

The line codes and processor codes listed in these tables are unique 
to CICS/VS and are represented as standard EBCDIC characters. 
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I KEY 


ENGRAVING 


LINE | 


1 No. 


Top(LC) 


Front (UC) 


Code | 


1 o 


MSG ACK 


1 


F1 | 


| 1 


SEND AGAIN 


Q 


D8 | 


I 2 


CORR 


A 


C1 | 


I 3 


HOLD OVRDE 


2 


F2 | 


I 4 


VOID 


Z 


E9 | 


I 5 


ACCT INQ 


W 


E6 | 


I 6 


ACCT TFR 


s 


E2 | 


I 7 


CIF 


3 


F3 | 


I 8 


MISC 


X 


E7 | 


I 9 


CLSD ACCT 


E 


C5 | 


| 10 


NO BOOK 


D 


C4 | 


| 11 


MORT LOAN 


4 


F4 | 


I 12 




C 


C3 | 


I 13 


NEW ACCT 


R 


D9 | 


| 14 


BOOK BAL 


F 


C6 | 


I 15 


INST LOAN 


5 


F5 | 


I 16 


SPEC TRAN 


V 


E5 | 


I 17 


SAV BOND 


T 


E3 | 


| 18 


SAV 


G 


C7 | 


| 19 


XMAS CLOB 


6 


F6 | 


| 20 


e 


B 


C2 | 


I 21 


DDA 


Y 


E8 | 


| 22 


oo 


H 


C8 | 


| 23 


HON ORD 


7 


F7 | 


| 24 | 





N 


D5 | 


| 25 


7 


U 


E4 | 


| 26 


4 


J 


D1 | 


| 27 


CSHR CHK 


8 


F8 | 


| 28 


1 


M 


D4 | 


| 29 


8 


I 


C9 | 


| 30 


5 


K 


D2 | 


I 31 


CASH RECD 


9 


F9 | 


I 32 


2 


i 


6B | 


| 33 


9 





D6 | 


| 34 


6 


L 


D3 | 


I 35 


UTIL BILL 





FO | 


I 36 


3 


e 


4B | 


I 37 


DEP + 


P 


D7 | 


I 38 


WITH - 


$ 


5B | 


| 39 


FEES 


— 


60 | 


| 40 


TOTL 


/ 


61 | 


| 41 


CASH IN 


l * 


5C | 


| 42 


CASH CHK 


# 


7B | 


I 43 


VAL 


5 


50 | 


| 44 


TAB 




05 | 


| 45 


ALPHA ENTRY 




36 | 


I 46 


NDM ENTRY 




I 06 | 


| 47 


SEND 




26-ETB| 
03-ETX| 


| 48 


| RETURN 




15 | 


| 49 


NUM ENTRY 




I 06 | 


| 50 


SPACE 




40 | 


| 58 


MSGLIGHT 




17 | 



CPU CODE 
Numeric (LC) Alpha (UC) 




AA 
D9 
C3 
C8 
E5 
D8 
AB 
AC 
AD 
E7 
AE 
AF 
BO 
B1 
B2 
B3 
B4 
B5 
B6 
B7 
4B 
B8 
B9 
BA 
FO 
F7 
F4 
BB 
F1 
F8 
F5 
BC 
F2 
F9 
F6 
E4 
F3 
4E 
60 
C6 
E3 
BD 
BE 
STATION ID 
05 



15 



40 
17 



F1 

D8 
C1 
F2 
E9 
E6 
E2 
F3 
E7 
C5 
C4 
F4 
C3 
D9 
C6 
F5 
E5 
E3 
C7 
F6 
C2 
E8 
C8 
F7 
D5 
E4 
D1 
F8 
D4 
C9 
D2 
F9 
6B 
D6 
D3 
FO 
4B 
D7 
5B 
60 
61 
5C 
7B 
50 
05 



15 

40 
17 



2 
3 
4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 
17 



18 



19 



20 
21 

TABCHAR 



JRNLCR 



MSGLITE 



Figure D-1. 2980-1 Character Set/Translate Table 
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1 

| KEY 




ENGRAVING 


| LINE 




CPU CODE 




HLL | 


| No. 


I Top (LC) Front 


(UC) i | Cod9 


Numeric (LC) 


Alpha (UC) 


ID | 


1 o 


= 


1 I 


1 F1 


F1 


(1) 


7E 


[=) 




I 1 


Q 




| D8 


98 


(q) 


D8 ( 


Q) 




I 2 


A 




| C1 


81 


(a) 


C1 


[M 




I 3 


2 




| F2 


F2 


(2) 


4C 


[<) 




I 4 


Z 




| E9 


A9 


(z) 


E9 | 


[Z) 




I 5 


W 




| E6 


A6 


(w ) 


E6 


(W) 




I 6 


s 




| E2 


A2 


(s) 


E2 


S) 




I 7 


t 


3 I 


| F3 


F3 


(3) 


5E | 


;) 




I 8 


X 




I E7 


A7 


(x) 


E7 ( 


X) 




I 9 


E 




I C5 


85 


(e ) 


C5 


[E> 




I 10 


D 




| C4 


| 84 


(d) 


C4 | 


D) 




I 11 


: 


* I 


| F4 


F4 


(4) 


7A 


[:) 




I 12 


c 




| C3 


83 


(c) 


C3 


(C) 




I 13 


R 




| D9 


99 


(r) 


D9 < 


R) 




| 14 


F 




| C6 


86 


(f) 


C6 | 


F) 




I 15 


% 


5 I 


I F5 


F5 


(5) 


6C 


[%) 




I 16 


V 




I E5 


A5 


00 


E5 ( 


V) 




I 17 


T 




| E3 


| A3 


(t) 


| E3 i 


T) 




I 18 


G 




I C7 


87 


(g) 


C7 


[6) 




I 19 


i 


6 I 


| F6 


F6 


(6) 


7D 


(M 




| 20 


B 




| C2 


82 


(*>) 


C2 ( 


B) 




I 21 


Y 




| E8 


A8 


(y) 


E8 i 


Y) 




| 22 


H 




| C8 


88 


On 


C8 


[H) 




I 23 


> 


7 I 


I F7 


F7 


(7) 


6E i 


>) 




| 24 


N 




| D5 


95 


(n) 


D5 i 


N) 




I 25 


U 




| E4 


A4 


(u ) 


E4 


(0) 




| 26 


3 




| D1 


91 


(j) 


D1 


[J) 




| 27 


* 


8 I 


| F8 


F8 


(8) 


5C ( 


*) 




| 28 


M 




| D4 


94 


(m) 


D4 i 


M) 




| 29 


I 




| C9 


89 


(i) 


C9 


(I) 




| 30 


K 




| D2 


92 


(k) 


D2 


[K) 




I 31 


( 


9 I 


| F9 


F9 


(9) 


4D ( 







| 32 


1 


r I 


| 6B 


6B 


\r i 


4F 


[I) 




I 33 







| D6 


96 


(o) 


D6 


O) 




| 34 


L 




| D3 


93 


(1) 


D3 < 


L) 




I 35 


) 


I 


| F0 


F0 


(0) 


5D i 


)) 




I 36 | 


-i 


. I 


| 43 


4B 


( • ) 


5F 


h) 




I 37 


P 




I D7 


97 


(P) 


D8 { 


P) 




| 38 


j 


$ I 


| 53 


5B 


($) 


5A i 


!) 




I 39 




— I 


| 60 


60 


(— ) 


6D | 


J 




| 40 


t" 


/ I 


I 61 


61 


(/) 


6F i 


?) 




| 41 


^ 


I I 


I 5C 


70 


(1) 


4A I 


0) 




| 42 


ii 


* I 


I 7B 


7B 


(#) 


7F i 


") 




| 43 


+ 


& I 


I 50 


50 


(&) 


4E 


[+) 




| 44 


TAB | 


I 05 | 


05 




05 






| 45 


LOCK | 


I 36 | 


36 




36 






| 46 


SHIFT | 


| 06 


06 




06 






| 47 


BACKSPACE | 


I 16 


10 




16 




BCKSPACE| 


| 48 


RETURN | 


I 15 


15 




15 






| 49 


SHIFT | 


| 06 


06 




06 






| 50 


(SPACE) | 


I 40 


40 




40 






| 53 


SEND | 


I26-ETB 












• 






I03-ETX 










» 



1 No keyfront engraving on a 2980 Administration Station Model 2 
Figure D-2 . 2980-2 Character Set/Translate Table 
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KEY 
No. 


1 
2 
3 

4 

5 

6 

7 

8 

9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 

48 
49 
50 
51 



ENGRAVING | 


Top(LC) 


Front (UC) | 


CK $ 


I 




Q I 




A I 


CK # 


I | 




z I 




W | 




s I 


IMD 2 


1 I 




X I 




E I 




D I 


IMD 1 


2 I 




C I 




R I 




F I 


CODE 


3 I 




V I 




T | 




G I 


AMT 


4 I 




B | 




Y I 




H I 


OB 


5 I 




N I 




U I 




J I 


ACCT # 


6 I 




N | 




I | 




K I 


7 


7 I 


4 


I 


1 


L I 


8 


3 I 





. 1 


5 


P I 


2 


$ I 


9 


9 I 


6 


*• I 


3 


# I 


VAL 


& I 


TAB 




ALPHA 




NUMERIC 




SEND 




RETURN 




NUMERIC 




SPACE 




FEED OPEN 





LINE 
Code 



D9 

D3 

C1 

C9 

E9 

E6 

E2 

5B 

E7 

C5 

C4 

4B 

C3 

60 

C6 

E8 

E5 

E3 

C7 

5C 

C2 

61 

D7 

D8 

D5 

E4 

D1 

C8 

D4 

D6 

D2 

F7 

6B 

F4 

F1 

F8 

F0 

F5 

F2 

F9 

7B 

F6 

F3 

50 

05 

36 

06 
26-ETB 
03-ETX 

15 

06 

40 

04 



CPU CODE | 


Numeric (LC) 


Alpha (UC) | 


BC 


60 | 


D3 


D8 | 


C1 


C1 | 


B7 


C9 | 


4B 


E9 | 


5C 


E6 | 


5B 


E2 | 


4F 


F1 I 


AE 


E7 | 


C5 


C5 | 


6F 


C4 | 


BF 


F2 | 


C3 


C3 | 


60 


D9 | 


C6 


C6 | 


BB 


F3 | 


A0 


E5 | 


A1 


E3 | 


C7 


I C7 | 


BE 


F4 | 


C2 


C2 | 


61 


E8 | 


D7 


C8 | 


B2 


F5 | 


D5 


D5 | 


AF 


E4 | 


D1 


D1 | 


7B 


F6 | 


E7 


D4 | 


D6 


C9 | 


D2 


D2 | 


F7 


F7 | 


BLANK 


6B | 


F4 


D6 | 


F1 


D3 | 


F8 


F8 | 


FO 


4B | 


F5 


D7 | 


F2 


5B | 


F9 


F9 | 


BO 


7B | 


F6 


5C | 


F3 


7B | 


50 


50 | 


05 


05 | 


15 


15 | 


40 


40 | 



HLL 
ID 



19 



14 



22 
23 

21 



OPENCH 



Figure D-3. 298 0-4 Character Set/Translate Table 
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The availability of a publication is indicated by its use key, which is 
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are: 

G — Generally available: Provided to users of IBM systems, 

products, and services without charge, in quantities to meet 
their normal requirements. Can also be purchased by anyone 
through IBM branch offices. 

S — Sold: Can be purchased by anyone through IBM offices. 

L — Licensed material, property of IBM: Available only to 

licensees of the related program products under the terms of 
the license agreements. 
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DFHTS 447 
ENTRY type of DFHTR macro 508 
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EOC operand 170 
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DFHTC 225 
EODPORG operand 

DFHBMS 311 
EODS (end of data set) 174 
EODS operand 
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DFHDI 336 

DFHTC 225 
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DFHTC 225 
error codes 

DFHBIF 

TYPE=PHONETIC 460 

phonetic conversion 460 
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DFHIC 363 
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extended search option 
extrapartition data sets 

alignment requirements 424 

data 417 

forced end of volume 426 

indirect destinations 417 

queue 417 



facilities for logical units 169 
FCADDE operand 

DFHKC 387 
FEOV type of DFHTD macro 426 
field definition macro (BHS) 265 
field edit 

macro instruction 465 
operation 465 
returned values 465 
FIELD operand 

DFHBIF 488 
field verify 
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operation 463 
returned values 463 
FIELDS operand 
DFHBIF 488 
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file management 73 
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priority of 74 

program examples 
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check response code 124 
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access 94 
random update or add data 97 
releasing an FWA 104 
reset sequential retrieval 118 
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summary of 6 
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GETJCA type of DFHJC macro 525 
GETMAIN type of DFHSC macro 410 
GETNEXT type of DFHFC macro 109 
GETPREV type of DFHFC macro 114 
GETQ type of DFHTS macro 441 
GRPNAME operand 
DFHMDF 269 



hard request— change— direction signal 
HEADER operand 
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DFHMDI 261 
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DFHMDF 269 

DFHMDI 261 

DFHMSD 253 
HTAB operand 

DFHMSD 254 



I/O PCB (input/output program control 

blocks) 136 
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DFHIC 363 
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DFHFC 127 
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operation 470 
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journal control area (JCA) (continued) 
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acguire the journal control area 525 
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summary of 7 
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MAP type of DFHBMS macro 277 

MAP type of DFHMSD macro 248 
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MAPFAIL operand 
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MAPSET operand 
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mass insert 103 
MATCH operand 
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media selection in logical unit 331 
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message recovery, BMS 303 
message routing 295 

disposition and message routing 296 

DL/I restrictions 295 
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status flag byte 297 
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MODE operand 
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DFHMSD 254 
move mode 88 
MSETADR operand 
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NAMES operand 

DFHBIF 492 
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node error program 171 
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OBFMT operand 
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DFHMSD 255 
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DFHBMS 319 
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DFHBFTCA 455 
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DFHBIF 494 
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DFHBIF 494 
page building 
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examples 283 
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justify operands 282 

LINE operand 282 
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operation 238 

overflow processing 287,289 

paging commands on video devices 305 
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without mapping 290 
page gueuing facility 434 
page— out operations 17 
PAGEBLD type of DFHBMS macro 280 
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PFXLGTH operand 
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error codes 460 
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operation 460 
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subroutine 461 
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PICIN operand 

DFHMDF 272 
PICOOT operand 

DFHMDF 273 
pipeline logical unit (3600) 208 
pipeline logical unit (3650) 210 
PL/I 
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CWA, common work area 60 

FIOA, file I/O area 61 

FHA, file work area 62 
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program examples (see program examples) 

REENTRANT requirements 59 

register usage 19 

restrictions 22 
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storage definitions 59 
example of copying 66 
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entry 60 
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TDOA, transient data output area 63 
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transfer of control 19 

TSIOA, temporary storage I/O area 64 

TWA, transaction work area 60 

VSWA, VSAM work area 62 
polling of terminals 161 
POS operand 

DFHMDF 266,274 
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posting ECBs 369 
PRGNAME operand 

DFHTC 227 
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print reguest facility (3270) 198 
printer authorization matrix 197,198,200 
printer control characters (BMS) 304 
priority of a task 373 

program communication blocks (PCB) 135 
program examples 

basic mapping support (BMS) 561 
map definition 561 
test response code 302 

built— in functions 
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BIF 455 
table search using complex 
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check response code 124 
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reset sequential retrieval 118 
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VSAM locate mode I/O 91 
journal services 

acquire the journal control 
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asynchronous journal output 532 

journal record synchronization 536 

synchronous journal output 527 
partial dump request 518 
posting ECBs 369 
storage services 

abnormally terminate a 
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check response code 4 05 

deleting a program 396 

establish program exit 401 

linking programs 391 

loading a program 393 
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release main storage 412 

transferring program control 392 
task services 

attaching tasks 371 

change priority of a task 373 

multiple events task 
synchronization 377 

relinquish control to higher 
priority task 378 

single event task 
synchronization 375 

single— server resource 
synchronization 381 
temporary storage services 

check response code 445 

free temporary data 442 

retrieve temporary data 438 
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program examples (continued) 
tine services 

check response code 361 
retrieval of time-ordered data 356 
signal for time expired 349 
suspend task processing 346 
task initiation with data 353 
task initiation without data 351 
time— of -day services 344 
transient data services 

acguire queued data 423 
check response code 429 
dispose of data 421 
extrapartition alignment 

requirements 424 
forced end of volume 426 
weighted retrieval 484 
program initialization 19 
PROGRAM operand 

DFHPC 407 
program services 
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relationships 389 
convert label to address 403 
delete a program 396 
introduction to 389 
load a program 393 
logical levels 389 
macro instruction 391 
pass control anticipating return 391 
program management 389 
response codes 4 04 
return program control 395 
summary of 7 
test response 404 
transfer control 392 
program specification blocks (PSB) 135 
program testing and debugging 

card— reader— in/line— printer-out 

(CRLP) 501 
dump services 513 
introduction to 49 6 
sequential terminal support 501 
trace services 503 
programming considerations 
data base considerations 

adding records to DAM data sets 84 
PROPT operand 

DFHBMS 321 
PRTY operand 

DFHKC 387 
PS operand 255 
DFHMDF 273 
DFHMDI 263 
DFHMSD 255 
PSB (program specification blocks) 135 
PSB operand 

DFHFC DL/I services 15 3 
PSBFAIL operand 

DFHFC DL/I services 153 
PSBNA operand 

DFHFC DL/I services 153 
PSBNF operand 

DFHFC DL/I services 153 
PSBSCH operand 
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PURGE type of DFHTD macro 427 
PURGE type of DFHTS macro 443 
PUT type of DFHFC macro 96 
PUT type of DFHIC macro 352 
PUT type of DFHJC macro 527 
PUT type of DFHTC macro 166 
PUT type of DFHTD macro 421 
PUT type of DFHTS macro 435 
PUTQ type of DFHTS macro 437 
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DFHKC 387 
QARGLNG operand 
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quasi— reenterability 18 
QUEBUSY operand 

DFTD macro 431 
QDEZERO operand 

DFHTD macro 431 
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retrieval for update 
example of 92 

retrieval via indirect access 94 

update or add data 
example of 97 
RANGE operand 

DFHBIF 494 
RCD signal 175 
RDATA1 operand 

DFHTR 510 
EDATA2 operand 

DFHTR 510 
RDATT operand 

DFHBMS 321 

DFHTC 228 
RDIDADR operand 81 

DFHBIF 496 

DFHFC 131 

structure 81 
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read from a terminal or LU 163 
read— ahead queueing 169 
ready message for 7770 166 
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duplicate 79 

segmented 75 
record identification 

address of 131 
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DAM data set 82 

ISAM data set 81 

multiple browse 81 

RDIDADR operand 81 

VSAM data set 81 
recovery/restart services 

summary of 7 

sync point management 545 
reenterable program 17 
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RELEASE operand 

DFHIC 365 

DFHSC 416 
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RELEASE type of DFHFC macro 103 
RELEASE type of DFHTS macro 442 
elinquish control to higher priority 
task 377 
replacement of records (DFHDI macro) 329 
REQID operand 

DFHBMS 321 

DFHIC 365 
request-change— direction signal 175 
request/response unit (RO) 170 
RESETL type of DFHFC macro 118 
RESETXIT type of DFHPC macro 402 
response codes 

DL/I services 143 

file control 121 

interval control 360 

journal control 539 

methods of testing 23 

program control 40 4 

temporary storage control 444 

transient data control 428 
response codes (DFHDI macro) 335 
restart (see recovery/restart) 
restore recoverable resources 546 
restrictions 

Assembler language 20 

COBOL 2 

link— editing 22 

object module size 23 

overlays in application programs 17 

PL/I 22 
RETMETH operand 

DFHFC 132 
RETPAGE operand 

DFHBMS 322 
retrieve time— ordered data 355 
RETRY type of DFHIC macro 359 
return program control 39 5 
RETURN type of DFHPC macro 395 
ROLLBACK type of DFHSP macro 546 
ROUTE type of DFHBMS macro 296 
ROUTINE operand 

DFHPC 4 07 
RRNADDR operand 

DFHDI 337 
RTEFAIL operand 

DFHBMS 322 
RTESOME operand 

DFHBMS 322 
RU (request/response unit) 170 
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DFHBMS TYPE=IN 279 

DFHBMS TYPE=MAP 277 
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SCSPRT logical unit 202 
SEGIDER operand 

DFHFC 132 
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segment set identification 

SEGSET operand 133 
segmented record 75 

general rules 75 
segmented writes control (2980) 192 
SEGSET operand 
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DFHDI 337 
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SELNERR operand 
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SEND/RECEIVE mode 169 
sequential 

terminal support 501 
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reset sequential retrieval 118 

retrieve next sequential record 109 

retrieve previous sequential record 114 

skip— sequential processing 75 

start browse 105 

terminate sequential retrieval 116 
service invocation 

file services 73 

journal services 523 

program services 389 

recovery/restart services 545 

storage services 409 
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temporary storage services 433 
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time services 34 3 

transient data services 417 
SERVICE RELOAD 55 
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SETXIT type of DFHPC macro 399 
SIGADDR operand 

DFHTC 228 
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LU (logical unit) 

signal command 175 
single event task synchronization 375 
single threading 13 
SIZE operand 

DFHMDI 263 
skip— sequential processing 75,110 
SNA (Systems Network Architecture) 

system 161 
SNA protocols 169 
SRCHTYP operand 

DFHFC 133 
SSALIST operand 

DFHFC DL/I services 153 
SSAS operand 

DFHFC DL/I services 154 
standard attribute list (BMS) 304 
STARTIO operand 

DFHJC 543 
STATERR operand 
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addressability of 
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COBOL 53 
PL/I 64 

storage definition 

Assembler language 43 
COBOL 53 
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storage areas 
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chaining 32 
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storage areas (continued) 
summary 29 
symbolic names 32 
storage definition 
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base addresses 31 
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common system area (CSA ) 

Assembler language 37 

COBOL 48 

PL/I 59 
common work area (CWA ) 

Assembler language 37 

COBOL 48 

PL/I 60 
copying 31 
file input/output area (FIOA) 

Assembler language 39 

COBOL 50 

PL/I 61 
file work area (FWA) 

Assembler language 40 

COBOL 51 
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Assembler language 43 
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PL/I 65 
recommendation 18 
required storage areas 33 
storage accounting area (SAA) 43 

Assembler language 43 

COBOL 53 

PL/I 64 
storage accounting field 27 
task control area (TCA) 

Assembler language 38 

COBOL 49 

PL /I 60 
temporary storage input/output area 
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Assembler language 42 

COBOL 52 

PL/I 64 
terminal control table terminal entry 
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Assembler language 38 

COBOL 48 

PL/I 60 
terminal input/output area (TIOA) 

Assembler language 39 

COBOL 49 

PL/I 61 
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Assembler language 38 
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Assembler language 41 

COBOL 52 
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storage definitions 

Assembler language 37 
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STORAGE operand 

DFHMSD 255 
storage services 
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activate ABEND exit 399 

cancel ABEND exit 399 

introduction to 409 

macro instruction 410 

obtain and initialize main storage 410 

program examples 

abnormally terminate a 

transaction 397 
check response code 405 
deleting a program 396 
establish program exit 401 
linking programs 391 
loading a program 393 
obtain and initialize main 

storage 410 
release main storage 412 
transferring program control 392 

reactivate ABEND exit 400 

release main storage 412 

storage control 409 

storage management 409 

summary of 6 
STORCLS operand 

DFHTS 448 
STORFAC operand 

DFHTS 449 
strings, VSAM 104 
STYPE operand 

DFHTR 510 
SUBST operand 

DFB.BIF 496 
SUFFIX operand 256 

DFHMSD 256 
SUPPR operand 
suspend data set 434 
suspend execution of task (DFHDI 

macro) 333 
switchable screen sizes 197,199,200 
symbolic description map (BMS) 240 
sync point management 

summary of 7 

sync point 545 
sync point, specify 545 
synchronization of I/O 161 
synchronize a task 375 
synchronize terminal I/O 

DFHTC TYPE=WAIT 166 

return of control 166 
synchronous journal output 527 
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syntax of DFHTC macro 179 
system management functions 
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system management functions (continued) 

summary of 6 

task services 367 

temporary storage services 433 
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System/3 182 
System/370 182 
System/7 183 

systems network architecture (SNA) 
system 161 
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operation 457 
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